diff --git a/.changeset/khaki-jars-repeat.md b/.changeset/khaki-jars-repeat.md
new file mode 100644
index 00000000..aad52bba
--- /dev/null
+++ b/.changeset/khaki-jars-repeat.md
@@ -0,0 +1,11 @@
+---
+'@noormdev/sdk': patch
+---
+
+Put `types` first in the package exports map
+
+Export conditions are matched in order, so `types` sitting after `import` is
+resolvable only by luck — it works today because there is no `require`
+condition to shadow it, and would silently stop working the moment one was
+added. `publint` reports it as an error. Also normalized both packages'
+`repository.url` to the full `git+https://…​.git` form npm expects.
diff --git a/.changeset/olive-pugs-shave.md b/.changeset/olive-pugs-shave.md
new file mode 100644
index 00000000..76c8f289
--- /dev/null
+++ b/.changeset/olive-pugs-shave.md
@@ -0,0 +1,11 @@
+---
+'@noormdev/cli': patch
+---
+
+Read change-history timestamps as UTC on postgres and mysql
+
+`executed_at` has no time zone and noorm writes UTC into it, but `pg` and
+`mysql2` both read that back through the host's local zone. On a UTC-4 host a
+change applied a second ago was reported as four hours in the future, which
+surfaced in the TUI as "Applied ... in 4 hours" on the home screen and in
+change history. MSSQL is unchanged — its driver was not measured.
diff --git a/LICENSE b/LICENSE
index ee92eec1..d6456956 100644
--- a/LICENSE
+++ b/LICENSE
@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 Danilo Alonso
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 00000000..a58dd1f7
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,2 @@
+noorm
+Copyright 2026 Danilo Alonso
diff --git a/README.md b/README.md
index eac7d592..bcdddafe 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ Your schema lives in SQL files. noorm builds it, versions it, and keeps every en
 [![@noormdev/cli](https://img.shields.io/npm/v/@noormdev/cli?color=E05742&label=%40noormdev%2Fcli)](https://www.npmjs.com/package/@noormdev/cli)
 [![@noormdev/sdk](https://img.shields.io/npm/v/@noormdev/sdk?color=916336&label=%40noormdev%2Fsdk)](https://www.npmjs.com/package/@noormdev/sdk)
 [![CI](https://github.com/noormdev/noorm/actions/workflows/ci.yml/badge.svg)](https://github.com/noormdev/noorm/actions/workflows/ci.yml)
-[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+[![license](https://img.shields.io/badge/license-Apache%202.0-blue)](./LICENSE)
 
 **[Documentation](https://noorm.dev)** · **[Getting started](https://noorm.dev/getting-started/installation)** · **[Terminal UI](https://noorm.dev/tui)** · **[SDK](https://noorm.dev/reference/sdk)**
 
@@ -121,4 +121,4 @@ noorm also runs as an [MCP server](https://noorm.dev/guide/automation/mcp), behi
 
 ## License
 
-MIT
+Apache License 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 97599674..b4f72515 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -81,16 +81,15 @@ gtag('config', 'G-Y69K95866J');`],
             // https://vitepress.dev/reference/default-theme-config
             logo: '/image/logo.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".
             nav: [
-                { text: 'Home', link: '/' },
                 { text: 'Getting Started', link: '/getting-started/installation' },
                 { text: 'Guide', link: '/guide/sql-files/organization' },
                 { text: 'CLI', link: '/headless' },
                 { text: 'TUI', link: '/tui' },
-                {
-                    text: 'Dev Docs',
-                    link: '/dev/',
-                },
+                { text: 'Modeling', link: '/modeling/' },
             ],
 
             sidebar: {
@@ -105,6 +104,7 @@ gtag('config', 'G-Y69K95866J');`],
                             { text: 'Runner', link: '/dev/runner' },
                             { text: 'Settings', link: '/dev/settings' },
                             { text: 'State', link: '/dev/state' },
+                            { text: 'Project Discovery', link: '/dev/project-discovery' },
                         ],
                     },
                     {
@@ -118,6 +118,7 @@ gtag('config', 'G-Y69K95866J');`],
                             { text: 'Locking', link: '/dev/lock' },
                             { text: 'Teardown', link: '/dev/teardown' },
                             { text: 'Config Sharing', link: '/dev/config-sharing' },
+                            { text: 'Data Transfer', link: '/dev/transfer' },
                         ],
                     },
                     {
@@ -144,20 +145,44 @@ 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' },
                             { text: 'Concepts', link: '/getting-started/concepts' },
                         ],
                     },
+                    // Only Getting Started and Reference omit `collapsed`, which
+                    // 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
+                        // out to the ignatius repo for the exhaustive rule
+                        // catalogs rather than duplicating them here.
+                        text: 'Information Modeling',
+                        collapsed: true,
+                        items: [
+                            { text: 'Overview', link: '/modeling/' },
+                            { text: 'Installation', link: '/modeling/installation' },
+                            { text: 'Entities & Key Inheritance', link: '/modeling/entities' },
+                            { text: 'Data Flows', link: '/modeling/data-flows' },
+                            { 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: 'SQL Files',
                         collapsed: true,
@@ -175,6 +200,10 @@ gtag('config', 'G-Y69K95866J');`],
                             { text: 'Stages', link: '/guide/environments/stages' },
                             { text: 'Secrets', link: '/guide/environments/secrets' },
                             { text: 'Vault', link: '/guide/environments/vault' },
+                            // Identity is what makes vault sharing and config
+                            // export work, so it belongs beside them even though
+                            // the page lives under /cli/.
+                            { text: 'Identity', link: '/cli/identity' },
                         ],
                     },
                     {
@@ -201,6 +230,7 @@ gtag('config', 'G-Y69K95866J');`],
                         collapsed: true,
                         items: [
                             { text: 'CI/CD', link: '/guide/automation/ci' },
+                            { text: 'Deployment', link: '/guide/deployment' },
                             { text: 'MCP (AI Agents)', link: '/guide/automation/mcp' },
                         ],
                     },
@@ -208,13 +238,18 @@ gtag('config', 'G-Y69K95866J');`],
                         text: 'Reference',
                         items: [
                             { text: 'SDK', link: '/reference/sdk' },
+                            { text: 'Contributor Documentation', link: '/dev/' },
                         ],
                     },
                 ],
             },
 
+            // Two GitHub repos, so both need an explicit ariaLabel: the default
+            // is the icon name, which would announce both as just "github".
+            // brand.css captions them so they are told apart visually too.
             socialLinks: [
-                { icon: 'github', link: 'https://github.com/noormdev/noorm' },
+                { icon: 'github', link: 'https://github.com/noormdev/noorm', ariaLabel: 'noorm on GitHub' },
+                { icon: 'github', link: 'https://github.com/noormdev/ignatius', ariaLabel: 'ignatius on GitHub' },
             ],
 
             search: {
@@ -235,7 +270,9 @@ gtag('config', 'G-Y69K95866J');`],
 
             footer: {
                 message: 'Database Schema & Change Manager',
-                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> · ISC License`,
+                // 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>`,
             },
         },
     }),
diff --git a/docs/.vitepress/theme/HeroEyebrow.vue b/docs/.vitepress/theme/HeroEyebrow.vue
index 20805fea..ac637718 100644
--- a/docs/.vitepress/theme/HeroEyebrow.vue
+++ b/docs/.vitepress/theme/HeroEyebrow.vue
@@ -1,5 +1,7 @@
 <template>
-    <div class="hero-eyebrow">V1.0 · ISC · POSTGRES · MYSQL · SQLITE · MSSQL</div>
+    <!-- Apache-2.0 to match LICENSE and every package.json. This said ISC until
+         2026-08 and was the most visible license claim on the site. -->
+    <div class="hero-eyebrow">V1.0 · APACHE 2.0 · POSTGRES · MYSQL · SQLITE · MSSQL</div>
 </template>
 
 <style scoped>
diff --git a/docs/.vitepress/theme/brand.css b/docs/.vitepress/theme/brand.css
index 15fcc595..b4af1783 100644
--- a/docs/.vitepress/theme/brand.css
+++ b/docs/.vitepress/theme/brand.css
@@ -214,9 +214,13 @@ code, kbd, samp, pre {
    Terminal recordings and TUI stills (docs/tapes/)
    ───────────────────────────────────────────── */
 .vp-doc img[src$=".gif"],
-.vp-doc img[src*="/image/tui/"] {
+.vp-doc img[src*="/image/tui/"],
+.vp-doc video {
     display: block;
     width: 100%;
+    /* The <video> carries intrinsic width/height so the poster reserves its
+       box before load; height:auto keeps that from fighting width:100%. */
+    height: auto;
     margin: 24px 0;
     /* Same treatment as the code blocks these sit next to — the recordings are
        terminal output, so they should read as the same kind of surface. */
@@ -525,3 +529,45 @@ html.dark {
         font-family: var(--vp-font-family-mono);
     }
 }
+
+/* ─────────────────────────────────────────────
+   Social links
+   ───────────────────────────────────────────── */
+
+/* Two GitHub icons sit here, one per repo, so each needs a caption to be
+   told apart. VPSocialLink renders its icon with v-html, which discards
+   any child node, so the caption has to be a pseudo-element.
+   Doubled container class beats the component's own scoped rule, which
+   carries a data-v attribute and so lands at specificity (0,2,0). */
+.VPNavBarSocialLinks .VPSocialLink.no-icon,
+.VPNavScreenSocialLinks .VPSocialLink.no-icon {
+    flex-direction: column;
+    gap: 3px;
+    width: auto;
+    min-width: 36px;
+    padding: 0 6px;
+}
+
+.VPNavBarSocialLinks .VPSocialLink.no-icon::after,
+.VPNavScreenSocialLinks .VPSocialLink.no-icon::after {
+    font-size: 0.5rem;
+    line-height: 1;
+    letter-spacing: 0.02em;
+    color: var(--vp-c-text-3);
+    transition: color 0.25s;
+}
+
+.VPNavBarSocialLinks .VPSocialLink.no-icon:hover::after,
+.VPNavScreenSocialLinks .VPSocialLink.no-icon:hover::after {
+    color: var(--vp-c-text-1);
+}
+
+/* Matched on the repo path rather than the full URL so a trailing slash or
+   a protocol change does not silently drop the caption. */
+.VPSocialLink[href*="noormdev/noorm"]::after {
+    content: 'noorm';
+}
+
+.VPSocialLink[href*="noormdev/ignatius"]::after {
+    content: 'ignatius';
+}
diff --git a/docs/cli/flags.md b/docs/cli/flags.md
index 48fc937e..d5745ea3 100644
--- a/docs/cli/flags.md
+++ b/docs/cli/flags.md
@@ -39,8 +39,8 @@ Examples:
     noorm -c packages/db run build
     noorm --cwd /repos/myapp change ff
 
-`--help`/`-h` and `--version` are also recognized outside this mechanism — that's citty's own
-framework behaviour, not a `noorm`-specific hoist.
+`--help`/`-h` and `--version`/`-v` are also recognized outside this mechanism — that's citty's
+own framework behaviour, not a `noorm`-specific hoist.
 
 An unrecognized flag placed before the subcommand is an error, not a silent no-op:
 
@@ -58,7 +58,7 @@ work after the subcommand name:
 
     noorm run build --dry-run
     noorm config list --json
-    noorm sql repl --yes
+    noorm secret rm OLD_KEY --yes
 
 Placed before the subcommand instead, none of them are honoured — `noorm --dry-run run build`
 is rejected exactly like `noorm --bogus-flag config list` above, naming `--dry-run` as the
diff --git a/docs/cli/identity.md b/docs/cli/identity.md
index 2c54d71e..06e52575 100644
--- a/docs/cli/identity.md
+++ b/docs/cli/identity.md
@@ -6,26 +6,30 @@ This guide covers noorm's cryptographic identity system — the keys that authen
 
 ## Overview
 
-noorm uses X25519 cryptographic identities for secure config sharing and audit tracking. Each identity is stored locally in `~/.noorm/identity.key` (private key) and `~/.noorm/identity.json` (metadata). The public key is derived deterministically from the private key, and the identity hash (`email + name + publicKey`) is stable across machines, so the same private key always resolves to the same identity.
+noorm uses X25519 cryptographic identities for secure config sharing and audit tracking. Each identity is stored locally in `~/.noorm/identity.key` (private key) and `~/.noorm/identity.json` (metadata). The public key is derived deterministically from the private key, so it never has to be stored separately to be recovered.
+
+A disk identity is hashed as `SHA-256(email + name + machine + os)`, where `machine` is the hostname. The same person on two laptops is therefore two identities in the audit trail, and each needs vault access propagated to it. Env-var identities hash differently on purpose, so a CI fleet reads as one user: see [Env-Var Identity (CI)](#env-var-identity-ci) below.
 
 For CI runners, identities load from environment variables instead of files — see the [CI automation guide](../guide/automation/ci.md) for end-to-end setup, including `noorm ci identity new` (generate keypair) and `noorm ci identity enroll` (grant vault access on a target database).
 
 
 ## Creating an Identity
 
-Run `noorm identity init` on your machine to create a keypair:
+Run `noorm identity init` on your machine to create a keypair. `--name` and `--email` are both required; the command does not prompt.
 
 ```bash
-noorm identity init
+noorm identity init --name "Alice Cooper" --email alice@example.com
 ```
 
-This prompts for your name and email, generates a keypair, and writes:
+This generates a keypair and writes:
 
-- Private key: `~/.noorm/identity.key`
-- Public key: `~/.noorm/identity.pub`
+- Private key: `~/.noorm/identity.key` (mode `0600`)
+- Public key: `~/.noorm/identity.pub` (mode `0644`)
 - Metadata: `~/.noorm/identity.json`
 
-The private key never leaves your machine — your public key is what teammates use to share encrypted state with you.
+The private key never leaves your machine. Your public key is what teammates use to share encrypted state with you.
+
+If an identity already exists, `init` refuses. Replacing it takes `--force --yes`, and it is destructive: state encryption is keyed off the private key, so every noorm project on the machine loses access to the configs, secrets, and database passwords in its `.noorm/state/state.enc`. Nothing re-encrypts existing state under the new key. noorm copies the old key files to `.bak-<timestamp>` siblings before overwriting, and aborts if it cannot. An ambient `NOORM_YES` does not satisfy this confirmation; only the literal `--yes` flag does.
 
 
 ## Editing Your Identity
@@ -62,11 +66,7 @@ noorm identity list --json
 
 When `NOORM_IDENTITY_PRIVATE_KEY`, `NOORM_IDENTITY_NAME`, and `NOORM_IDENTITY_EMAIL` are set at process startup, every `noorm` command in that process uses the env-derived identity without touching `~/.noorm/`.
 
-**Bootstrap order:**
-
-1. At startup (`entry()` in `src/cli/index.ts`), the CLI calls `loadIdentityFromEnv()`.
-2. If the three vars are present and valid, the key and metadata are installed as in-memory overrides.
-3. Every later call to `loadPrivateKey()` / `loadIdentityMetadata()` checks the override first — if set, it returns the env-derived values without reading disk.
+The variables are read once when the process starts, so they apply to every command that process runs.
 
 **Guarantees:**
 
diff --git a/docs/cli/init.md b/docs/cli/init.md
index ac86d16c..d2099464 100644
--- a/docs/cli/init.md
+++ b/docs/cli/init.md
@@ -27,8 +27,8 @@ Two flags opt out of that behavior, depending on where you want to invoke from:
 
 ## Environment
 
-Interactive TTY required by default. Fails with exit code 1 in CI or piped stdin
-unless `--yes` / `NOORM_YES=1` is set AND a full identity already exists.
+Interactive TTY required by default. Fails with exit code 2 (usage error) in CI or
+piped stdin unless `--yes` / `NOORM_YES=1` is set AND a full identity already exists.
 
 
 ## Non-interactive (CI) flow
@@ -36,7 +36,7 @@ unless `--yes` / `NOORM_YES=1` is set AND a full identity already exists.
 `noorm init --yes` (or `NOORM_YES=1 noorm init`) skips all prompts when a full
 crypto identity already lives at `~/.noorm/identity.{key,pub,json}`. The identity
 must be in place first — `--yes` does NOT bootstrap one. If any of the three
-files is missing, `noorm init --yes` exits 1 with:
+files is missing, `noorm init --yes` exits 2 with:
 
     Error: noorm init --yes requires an existing identity at ~/.noorm/identity.{key,pub,json}.
     Run: noorm identity init --name "Your Name" --email "you@example.com"
diff --git a/docs/cli/run.md b/docs/cli/run.md
index d2d03d87..3e32b952 100644
--- a/docs/cli/run.md
+++ b/docs/cli/run.md
@@ -1,9 +1,10 @@
 # noorm run
 
 
-Execute SQL files against the active database. There are five subcommands —
+Execute SQL files against the active database. Five subcommands execute SQL —
 `build`, `file`, `dir`, `files`, and `exec` — and they all share the same
-result shape and exit-code semantics.
+result shape and exit-code semantics. Two more, `inspect` and `preview`, read a
+`.sql.tmpl` file without touching the database.
 
 
 ## Subcommands
@@ -15,25 +16,31 @@ result shape and exit-code semantics.
 | `noorm run dir <path>` | Execute every file in a directory |
 | `noorm run files --paths a.sql,b.sql` | Execute an explicit, ordered list |
 | `noorm run exec <dir-or-glob>` | Discover files by glob, then execute |
+| `noorm run inspect <path>` | Show the template context for a `.sql.tmpl` file |
+| `noorm run preview <path>` | Render a `.sql.tmpl` file and print the SQL |
 
 
 ## Flags
 
-Common to every subcommand:
+Common to the five executing subcommands:
 
 - `--config <name>` / `-c <name>` — use a named config from `state.enc`
 - `--force` / `-f` — re-run even if the file's checksum matches a prior success
 - `--dry-run` — render templates and write to `tmp/` without executing
 - `--json` — emit machine-readable JSON on stdout
 
+`inspect` and `preview` take `--config` and `--json` only. Neither executes, so
+`--force` and `--dry-run` have nothing to act on.
+
 
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
 | `0` | Every file succeeded or was skipped |
-| `1` | Setup failed (could not connect, project not initialized, bad args) |
-| `2` | The runner ran but at least one file failed |
+| `1` | Total failure — setup failed (could not connect, project not initialized), or the runner ran and nothing succeeded |
+| `2` | Usage error — a missing flag, a directory or glob that matched no SQL files (`dir`, `exec`), or a template that isn't there (`inspect`, `preview`). Nothing was attempted |
+| `3` | Partial failure — some files succeeded and some failed. Re-running is not automatically safe |
 
 
 ## Output: failure
@@ -44,15 +51,19 @@ looking for the cause:
 
     sql/02_tables/Memory.sql (failed)
       error: relation "memory" does not exist
-    Build completed  status=failed filesRun=12 filesSkipped=0 filesFailed=1 durationMs=84
+    Build completed  status=partial filesRun=12 filesSkipped=0 filesFailed=1 durationMs=84
+
+A batch where some files ran and some failed reports `partial` and exits `3`.
+Only a batch where nothing succeeded reports `failed` and exits `1`.
 
 The same information lives on the JSON output's per-file entries. The
-`--json` payload is the unmodified `BatchResult` (or `FileResult` for
-`noorm run file`) returned by the SDK, so `files[].error` is populated
-for every failed file:
+`--json` payload is the `BatchResult` (or `FileResult` for `noorm run file`)
+returned by the SDK plus the envelope's `success` flag, so `files[].error` is
+populated for every failed file:
 
     {
-        "status": "failed",
+        "success": false,
+        "status": "partial",
         "files": [
             {
                 "filepath": "sql/02_tables/Memory.sql",
diff --git a/docs/cli/secret.md b/docs/cli/secret.md
index 76dc0860..d23560c0 100644
--- a/docs/cli/secret.md
+++ b/docs/cli/secret.md
@@ -10,7 +10,7 @@ places a secret value can live; see [Which tier?](#which-tier) below before reac
 
 | Command | Purpose |
 |---------|---------|
-| `noorm secret set <key> <value>` | Store a secret for the active or named config |
+| `noorm secret set <key> [value]` | Store a secret for the active or named config |
 | `noorm secret list` | List secret keys for a config (values never shown) |
 | `noorm secret rm <key>` | Remove a secret from a config |
 
@@ -22,6 +22,11 @@ Common to every subcommand:
 - `--config <name>` / `-c <name>` — target a config other than the active one
 - `--json` — emit machine-readable JSON on stdout
 
+`secret set` additionally accepts:
+
+- `--stdin` — read the value from stdin instead of argv, so it never reaches the process table, shell history, or a `set -x` trace. Omit the positional value when you pass it.
+- `--yes` / `-y` — confirm the write on a config whose `secret:write` access is a confirm cell (an `operator` user role). Without it the command exits non-zero.
+
 `secret rm` additionally requires:
 
 - `--yes` / `-y` — confirm the deletion; omitted, the command exits non-zero without deleting
@@ -53,6 +58,7 @@ team-provisioning workflow.
 ## Examples
 
     noorm secret set API_KEY "sk-live-..."
+    echo "$API_KEY" | noorm secret set API_KEY --stdin
     noorm secret set DB_PASSWORD "secret123" --config prod
     noorm secret set API_KEY "sk-live-..." --json
 
diff --git a/docs/cli/settings-edit.md b/docs/cli/settings-edit.md
index 9e84cce8..3df3c810 100644
--- a/docs/cli/settings-edit.md
+++ b/docs/cli/settings-edit.md
@@ -7,7 +7,7 @@ logging, stages, conditional rules, teardown.
 
 ## Environment
 
-Interactive TTY required. Fails with exit code 1 in CI or piped stdin.
+Interactive TTY required. Fails with exit code 2 (usage error) in CI or piped stdin.
 
 `settings.yml` is plain YAML, so `--yes` / `NOORM_YES` has no useful
 non-interactive path here. Both produce a redirect hint pointing you at
diff --git a/docs/cli/settings-secret.md b/docs/cli/settings-secret.md
index 991d353d..16c7b8c5 100644
--- a/docs/cli/settings-secret.md
+++ b/docs/cli/settings-secret.md
@@ -10,7 +10,7 @@ For secret values, see [`noorm secret set`](./secret.md).
 
 ## Environment
 
-Interactive TTY required. Fails with exit code 1 in CI or piped stdin.
+Interactive TTY required. Fails with exit code 2 (usage error) in CI or piped stdin.
 
 `--yes` / `NOORM_YES` produces a redirect hint here — the requirement
 list lives directly in `settings.yml`, so editing the YAML by hand is the
diff --git a/docs/cli/sql-repl.md b/docs/cli/sql-repl.md
index 3dc5a220..46b7c2de 100644
--- a/docs/cli/sql-repl.md
+++ b/docs/cli/sql-repl.md
@@ -14,7 +14,7 @@ For one-off non-interactive queries (CI scripts, ad-hoc inspection), use [`noorm
 
 ## Environment
 
-Interactive TTY required. Fails with exit code 1 in CI or piped stdin.
+Interactive TTY required. Fails with exit code 2 (usage error) in CI or piped stdin.
 
 A REPL is interactive by definition, so `--yes` / `NOORM_YES` cannot make it
 succeed. They produce a redirect hint instead, pointing at `noorm sql query`
diff --git a/docs/cli/sql.md b/docs/cli/sql.md
index ea7fabf9..fe0060a7 100644
--- a/docs/cli/sql.md
+++ b/docs/cli/sql.md
@@ -35,6 +35,13 @@ The shorter `noorm sql "<SQL>"` form is also supported. Internally, the CLI insp
 
 The rewrite is purely positional — it never modifies the actual SQL string or flags. The real subcommands (`query`, `history`, `clear`, `repl`) are reserved words that never trigger the rewriter.
 
+The rewriter reads the *first non-flag token* after `sql`, so a flag that takes a value puts something else there and no rewrite happens:
+
+    noorm sql -f reports/monthly.sql       # → "Unknown command reports/monthly.sql"
+    noorm sql -c prod "SELECT 1"           # → "Unknown command prod"
+
+Both need the explicit form (`noorm sql query -f …`, `noorm sql query -c prod "…"`). A leading `--json`, which takes no value, is fine: `noorm sql --json "SELECT 1"` still rewrites.
+
 
 ### Flags (on `query`)
 
@@ -51,8 +58,8 @@ The rewrite is purely positional — it never modifies the actual SQL string or
 For interactive use and history management:
 
 - [`noorm sql repl`](./sql-repl.md) — launch the TUI on the SQL terminal screen
-- `noorm sql history` — list recent queries
-- `noorm sql clear` — wipe the saved history
+- `noorm sql history` — list recent queries (`-n`/`--limit`, default 50). Only the interactive SQL terminal records history; `sql query` deliberately writes none.
+- `noorm sql clear --yes` — wipe the saved history (`--older-than <months>` to keep recent entries). Without `--yes` it prints what it would clear and exits without clearing.
 
 
 ## Examples
diff --git a/docs/dev/change.md b/docs/dev/change.md
index c503305c..48a5940d 100644
--- a/docs/dev/change.md
+++ b/docs/dev/change.md
@@ -91,7 +91,10 @@ const manager = new ChangeManager({
     identity,
     projectRoot: process.cwd(),
     changesDir: '/project/changes',
-    schemaDir: '/project/sql',
+    sqlDir: '/project/sql',
+    access: config.access,   // per-channel roles from the config
+    channel: 'user',         // 'user' for CLI/TUI/SDK, 'agent' for MCP
+    dialect: 'postgres',     // defaults to 'postgres' when omitted
 })
 
 // List all changes with status
@@ -143,6 +146,13 @@ Batch operations (`next`, `ff`, `rewind`) add:
 |--------|---------|-------------|
 | `abortOnError` | `true` | Stop on first failure |
 
+Batch results (`BatchChangeResult`) carry `warnings?: string[]` for conditions
+that silently shrink a batch to nothing — currently a missing changes directory.
+A mistyped `paths.changes` otherwise reports `executed: 0` and exit 0, which is
+indistinguishable from an already-up-to-date database. `error?: string` carries
+a pre-flight failure that no per-change result can explain (e.g. a rewind target
+matching no applied change).
+
 
 ## Scaffolding
 
@@ -206,22 +216,29 @@ Each change has a status based on its execution history:
 | `success` | Applied successfully |
 | `failed` | Last execution failed |
 | `reverted` | Was applied, then reverted |
+| `stale` | Applied, but its objects were torn down — needs re-run |
+
+These are the `OperationStatus` values from `core/shared`, shared with the runner.
+`isPendingChange(item)` is the one predicate every "what still needs applying"
+surface uses (`ff`, `next`, the SDK's `pending()`, the CLI picker): it returns
+true for `pending`, `reverted`, and `stale` on non-orphaned changes.
 
 The `list()` method returns items with additional metadata:
 
 ```typescript
 interface ChangeListItem {
     name: string
-    status: 'pending' | 'success' | 'failed' | 'reverted'
+    status: OperationStatus
     appliedAt: Date | null
     appliedBy: string | null
     revertedAt: Date | null
+    errorMessage: string | null
+    appliedHistoryId?: number | null  // history row id — the true apply-order key
     isNew: boolean         // Exists on disk but no DB record
     orphaned: boolean      // In DB but folder deleted from disk
-    errorMessage?: string  // Error message if status is 'failed'
     // Disk metadata (when change exists on disk)
     path?: string
-    date?: Date
+    date?: Date | null
     description?: string
     changeFiles?: ChangeFile[]
     revertFiles?: ChangeFile[]
@@ -229,10 +246,13 @@ interface ChangeListItem {
 }
 ```
 
+`appliedAt` is second-precision, so changes applied in the same `ff` tick tie;
+`rewind` breaks the tie on `appliedHistoryId`.
+
 
 ## Tracking Tables
 
-Change execution is recorded in the same tables as the runner:
+Change execution is recorded in the same tables as the runner. Names below are the MySQL/SQLite prefixed form; PostgreSQL and SQL Server use `noorm.change` and `noorm.executions` in a dedicated schema instead.
 
 **`__noorm_change__`** - Operation record:
 
@@ -241,7 +261,7 @@ Change execution is recorded in the same tables as the runner:
 | `name` | Change name |
 | `direction` | `'change'` or `'revert'` |
 | `change_type` | `'change'` |
-| `status` | `'pending'`, `'success'`, `'failed'` |
+| `status` | `OperationStatus`: `'pending'`, `'success'`, `'failed'`, `'reverted'`, `'stale'` |
 | `checksum` | Combined hash of all files |
 | `executed_by` | Identity string |
 
@@ -267,7 +287,7 @@ Change execution is recorded in the same tables as the runner:
 | `change:file` | `{ change, filepath, index, total }` | File being executed |
 | `change:complete` | `{ name, direction, status, durationMs }` | Execution finished |
 | `change:skip` | `{ name, reason }` | Change skipped (already applied, unchanged) |
-| `file:dry-run` | `{ filepath, outputPath }` | File written during dry-run mode |
+| `file:dry-run` | `{ filepath, status, outputPath?, error? }` | File rendered during dry-run mode |
 
 ```typescript
 import { observer } from './core/observer'
@@ -324,7 +344,7 @@ else if (err instanceof ManifestReferenceError) {
 | `ChangeOrphanedError` | In DB but folder deleted |
 | `ManifestReferenceError` | `.txt` references missing file |
 
-**Note**: Already-applied changes are not thrown as errors. Instead, they emit a `change:skip` event with `reason: 'already_applied'`. Use `--force` to re-run.
+**Note**: Already-applied changes are not thrown as errors. Instead, they emit a `change:skip` event with `reason: 'already applied'` and the change reports `status: 'success'` with zero files. Use `--force` to re-run. `ChangeAlreadyAppliedError` is exported but no longer thrown by the executor.
 
 
 ## Execution History
@@ -334,7 +354,10 @@ The `ChangeHistory` class provides detailed execution tracking:
 ```typescript
 import { ChangeHistory } from './core/change'
 
-const history = new ChangeHistory(db, 'production')
+// (db, configName, dialect) — dialect defaults to 'sqlite', which selects the
+// prefixed table names. Pass the real dialect or pg/mssql queries hit the
+// wrong identifiers.
+const history = new ChangeHistory(db, 'production', 'postgres')
 
 // Get status for a specific change
 const status = await history.getStatus('2024-01-15-add-users')
@@ -407,8 +430,8 @@ for (const file of files) {
 interface ChangeHistoryRecord {
     id: number
     name: string
-    direction: 'change' | 'revert'
-    status: 'pending' | 'success' | 'failed' | 'reverted'
+    direction: Direction          // 'change' | 'revert'
+    status: OperationStatus       // 'pending' | 'success' | 'failed' | 'reverted' | 'stale'
     executedAt: Date
     executedBy: string
     durationMs: number
@@ -416,17 +439,9 @@ interface ChangeHistoryRecord {
     checksum: string
 }
 
-interface UnifiedHistoryRecord {
-    id: number
-    name: string
-    changeType: 'change' | 'build' | 'run'
-    direction: 'change' | 'revert' | null
-    status: 'pending' | 'success' | 'failed' | 'reverted'
-    executedAt: Date
-    executedBy: string
-    durationMs: number
-    errorMessage: string | null
-    checksum: string
+// Adds the operation type; every other field is inherited unchanged.
+interface UnifiedHistoryRecord extends ChangeHistoryRecord {
+    changeType: 'build' | 'run' | 'change'
 }
 
 interface FileHistoryRecord {
@@ -435,7 +450,7 @@ interface FileHistoryRecord {
     filepath: string
     fileType: 'sql' | 'txt'
     checksum: string
-    status: 'pending' | 'success' | 'failed' | 'skipped'
+    status: ExecutionStatus       // 'pending' | 'success' | 'failed' | 'skipped'
     skipReason: string | null
     errorMessage: string | null
     durationMs: number
@@ -460,19 +475,28 @@ The `ChangeTracker` class extends the base `Tracker` with change-specific operat
 ```typescript
 import { ChangeTracker } from './core/change'
 
-const tracker = new ChangeTracker(db, configName)
+// (db, configName, dialect) — same signature as the base Tracker
+const tracker = new ChangeTracker(db, configName, 'postgres')
+
+// Check if a change can be reverted. `force` is required, and the result is a
+// CanRevertResult, not a boolean.
+const check = await tracker.canRevert('2024-01-15-add-users', false)
+// { canRevert: boolean, reason?: string, status?: OperationStatus, error?: Error }
 
-// Check if a change can be reverted
-const canRevert = await tracker.canRevert('2024-01-15-add-users')
+if (check.error) {
+    // State could not be established (unreadable/damaged tracking table) —
+    // distinct from an established "no".
+}
 
 // Mark a change as reverted
 await tracker.markAsReverted('2024-01-15-add-users')
 
-// Mark all changes as stale (used by teardown operations)
-await tracker.markAllAsStale()
+// Mark all changes as stale (used by teardown operations); returns the count
+const marked = await tracker.markAllAsStale()
 ```
 
 The base `Tracker` class (from `core/runner`) provides:
+- `needsRun()` / `needsRunByName()` - Change detection by filepath or name
 - `createOperation()` - Create operation records with direction
 - `createFileRecords()` - Create pending file records upfront
 - `updateFileExecution()` - Update individual file status
@@ -480,8 +504,8 @@ The base `Tracker` class (from `core/runner`) provides:
 - `finalizeOperation()` - Complete operation with final status
 
 `ChangeTracker` adds change-specific methods:
-- `canRevert()` - Check if change was successfully applied
-- `markAsReverted()` - Update status to 'reverted'
+- `canRevert(name, force)` - Check if change was successfully applied
+- `markAsReverted(name)` - Update status to 'reverted'
 - `markAllAsStale()` - Mark all applied changes for re-execution
 
 **Note:** `ChangeHistory` is now query-focused. Mutation methods (`canRevert`, `markAsReverted`, `markAllAsStale`) moved to `ChangeTracker`.
@@ -494,19 +518,25 @@ The `ChangeContext` interface includes all parameters needed for change executio
 ```typescript
 interface ChangeContext {
     db: Kysely<NoormDatabase>
-    dialect: Dialect             // Required for date formatting in locks
     configName: string
     identity: Identity
     projectRoot: string
     changesDir: string
-    schemaDir: string
+    sqlDir: string               // resolves .txt manifest references
+    access: ConfigAccess         // the config's per-channel roles
+    channel: Channel             // 'user' (CLI/TUI/SDK) or 'agent' (MCP or CLI)
     config?: Record<string, unknown>
     secrets?: Record<string, string>
     globalSecrets?: Record<string, string>
+    dialect?: 'postgres' | 'mysql' | 'sqlite' | 'mssql'  // default: 'postgres'
 }
 ```
 
-The `dialect` property is required because lock operations need dialect-specific date formatting.
+`access` and `channel` are required: `executeChange`/`revertChange` run the
+policy gate once, at the core seam, so SDK/TUI/CLI/MCP callers all inherit one
+enforcement path. `dialect` is optional and defaults to `'postgres'`; it selects
+the tracking-table naming (schema-qualified vs prefixed) and the date formatting
+lock operations need.
 
 
 ## Best Practices
diff --git a/docs/dev/ci.md b/docs/dev/ci.md
index 814bec79..60c5cf6a 100644
--- a/docs/dev/ci.md
+++ b/docs/dev/ci.md
@@ -31,34 +31,50 @@ noorm change ff
 
 `noorm ci init` reads identity and connection from env vars, writes an ephemeral `.noorm/state/state.enc`, creates a config (default name `ci`, override with `--name` or `NOORM_CI_CONFIG_NAME`), and marks it active. Later commands in the same job (`run build`, `change ff`, `ci secrets`) operate as if a developer had bootstrapped manually.
 
+Two preconditions worth knowing before wiring a pipeline:
+
+- It refuses to run when `.noorm/state/state.enc` already exists. `--force` backs the file up and replaces it; from an interactive terminal `--yes` is required as well, since replacing state destroys every config and config-scoped secret in the project.
+- The config it writes carries `isTest: true`. An SDK context created with `requireTest: true` will therefore accept it — do not rely on that guard to keep a CI job away from a production database.
+
 **One-time setup** (developer with vault access):
 
 Two approaches depending on your trust model:
 
 ```bash
 # Option A: Mint + enroll in one step (developer holds vault access)
-noorm ci identity enroll --config prod --name "GitHub CI" --email ci@example.com
+noorm ci identity enroll --config prod --name "GitHub CI" --email ci@example.com --yes
 # → prints NOORM_IDENTITY_PRIVATE_KEY / NAME / EMAIL once; copy to CI secrets store
 
 # Option B: Air-gapped (key minted on a separate machine)
 noorm ci identity new --name "GitHub CI" --email ci@example.com --json > ci-key.json
 # → gives the public key to a vault-holder, who enrolls it:
 noorm ci identity enroll --config prod --name "GitHub CI" --email ci@example.com \
-    --public-key <hex from ci-key.json>
+    --public-key <hex from ci-key.json> --yes
 ```
 
-`ci identity new` never contacts a database — it only generates a keypair and prints the env block. `ci identity enroll` registers the public key in the target database and grants vault access. Both are idempotent on identityHash.
+`ci identity new` never contacts a database — it only generates a keypair and prints the env block. Each run mints a *fresh* keypair, so it is not idempotent; re-running gives a different identity.
+
+`ci identity enroll` registers the public key in the target database and grants vault access. It is idempotent on identityHash: a second run with the same name/email/public key ensures vault access rather than inserting a duplicate. It refuses if a row already exists under that hash with a *different* public key — that shape is a pre-registration attack, not a retry.
+
+`--yes` is required on the first enroll. Enrollment is gated on `vault:propagate`, a `confirm` cell for every role that holds it (`viewer` is denied outright), because sealing the vault key to a public key cannot be undone. Without `--yes` the command prints the identity it is about to grant to and exits 1. It is skipped when the target already holds vault access, since confirming a no-op is noise.
 
 The full flow (with diagrams and per-provider examples) lives in the [CI automation guide](../guide/automation/ci.md).
 
 
 ## Exit Codes
 
+The `ci` commands follow the repo-wide contract in `src/cli/_exit.ts` — the same
+codes every other `noorm` command uses:
+
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
-| 1 | Configuration, connection, or precondition error (missing env vars, missing state, etc.) |
-| 2 | Partial success (e.g. `ci secrets` loaded some keys but others errored) or SQL build failure |
+| 1 | Total failure — nothing succeeded. `ci init` uses this when `state.enc` already exists without `--force`, or when state/config writes fail. |
+| 2 | Usage error — a bad invocation or a named target that does not exist. `ci init` uses this for missing/invalid `NOORM_IDENTITY_*` and missing `NOORM_CONNECTION_DIALECT`/`DATABASE`; `ci secrets` for an unreadable or unparseable `--file` and for an unknown config. Nothing was attempted. |
+| 3 | Partial — some units succeeded and some failed, e.g. `ci secrets` set some keys and errored on others. The target is in a mixed state; re-running is not automatically safe. |
+
+`3` rather than `2` for partial is deliberate: a clean failure can be retried,
+a partial one needs a human, so the two must never share a code.
 
 
 ## Environment Variables
diff --git a/docs/dev/config-sharing.md b/docs/dev/config-sharing.md
index 671754aa..6b11d7dd 100644
--- a/docs/dev/config-sharing.md
+++ b/docs/dev/config-sharing.md
@@ -18,6 +18,10 @@ Config sharing uses X25519 key exchange with AES-256-GCM encryption. Each user h
 
 Credentials (user/password) are intentionally excluded from exports. The recipient provides their own database credentials during import. This ensures shared configs don't contain hardcoded passwords.
 
+> **This flow is TUI-only.** It lives in `src/tui/screens/config/ConfigExportScreen.tsx` and `ConfigImportScreen.tsx`, reached from `noorm ui` → config list → `+` (more) → `[x]` export / `[i]` import.
+>
+> The `noorm config export` / `noorm config import` **CLI** commands are a different feature: plain, unencrypted JSON that *includes* the connection password, meant for backup and same-owner machine transfer. `config export` is gated on `secret:read` for exactly that reason. Do not send its output to a teammate.
+
 ```mermaid
 flowchart LR
     A[Alice's Config] --> B[Export]
@@ -47,7 +51,7 @@ sequenceDiagram
     participant Crypto as Crypto Module
     participant FS as File System
 
-    User->>CLI: noorm config:export myconfig
+    User->>CLI: config list → + → [x] export
     CLI->>User: Enter recipient email
     User->>CLI: bob@example.com
     CLI->>State: findKnownUsersByEmail(email)
@@ -75,6 +79,7 @@ The exported data includes everything needed to recreate the config except crede
         type: 'remote',
         isTest: false,
         access: { user: 'operator', agent: 'viewer' },
+        protected: true,        // legacy mirror of `access`, for old importers
         connection: {
             dialect: 'postgres',
             host: 'db.example.com',
@@ -83,18 +88,18 @@ The exported data includes everything needed to recreate the config except crede
             ssl: true,
             // NO user/password
         },
-        paths: {
-            sql: './sql',
-            changes: './changes',
-        },
     },
     secrets: {
-        'API_KEY': 'encrypted-value',
-        'WEBHOOK_SECRET': 'another-value',
+        'API_KEY': 'sk-live-...',        // plaintext inside the encrypted envelope
+        'WEBHOOK_SECRET': 'whsec-...',
     },
 }
 ```
 
+`access` is the source of truth; `protected` rides along so an as-yet-unupgraded importer still reaches a safe (if coarser) access decision. `paths` is *not* exported — the recipient's project layout is their own.
+
+The `secrets` map holds every config-scoped secret in the clear. It is protected only by the AES-256-GCM envelope around the whole JSON blob, so treat exporting as handing the recipient those values outright.
+
 
 ## Import Flow
 
@@ -114,7 +119,7 @@ sequenceDiagram
     participant Crypto as Crypto Module
     participant State as State Manager
 
-    User->>CLI: noorm config:import myconfig.noorm.enc
+    User->>CLI: config list → + → [i] import
     CLI->>FS: read myconfig.noorm.enc
     FS-->>CLI: SharedConfigPayload (encrypted)
 
@@ -142,7 +147,7 @@ sequenceDiagram
 
 ## Encryption Details
 
-noorm uses the ephemeral keypair pattern for perfect forward secrecy:
+noorm uses the ephemeral keypair pattern (ephemeral-static ECDH). HKDF is SHA-256 with an empty salt and the context string `noorm-config-share`; the IV is 16 random bytes per export:
 
 ```mermaid
 flowchart TB
@@ -188,6 +193,7 @@ Import can fail at several points. Each has a specific error message:
 | Error | Message | Cause |
 |-------|---------|-------|
 | File not found | `File not found: {path}` | Path doesn't exist |
+| Unreadable | `Could not read file.` | Path exists but the read failed (permissions, directory) |
 | Invalid format | `Invalid file format. Not a valid noorm export file.` | File isn't JSON or wrong structure |
 | No identity | `No private key found. Run "noorm init" first.` | Missing `~/.noorm/identity.key` |
 | Wrong recipient | `Could not decrypt file. You may not be the intended recipient.` | Decryption failed - wrong key |
@@ -198,7 +204,9 @@ Import can fail at several points. Each has a specific error message:
 
 ### Why Ephemeral Keypairs?
 
-Each export generates a fresh keypair. Even if someone obtains the recipient's private key later, they cannot decrypt old exports without the ephemeral private key (which is never stored).
+Each export generates a fresh keypair, so no two exports share a wrapping key and the sender needs no long-term secret of their own to encrypt.
+
+**This is not forward secrecy.** The exchange is ephemeral-static: the recipient's key is long-lived, and `decryptWithPrivateKey` needs nothing but that key plus the `ephemeralPubKey` stored in the file itself. Anyone who obtains the recipient's private key can decrypt every `.noorm.enc` file ever sent to them, past and future. Treat a leaked `~/.noorm/identity.key` as a compromise of every shared config and every secret in them.
 
 ### Why Exclude Credentials?
 
@@ -213,8 +221,9 @@ Forcing recipients to enter credentials ensures accountability.
 
 The `.noorm.enc` file can be shared via any channel (email, Slack, git) because:
 - Only the intended recipient can decrypt it
-- Tampering is detected via GCM authentication tag
-- Sender identity is verified via metadata
+- Tampering with the *ciphertext* is detected via the GCM authentication tag
+
+The `sender` and `recipient` fields are **not** authenticated. They sit alongside the ciphertext as plain JSON, and no AAD is bound into the GCM tag, so anyone can edit them without breaking decryption. They are display metadata, not proof of origin — a successful decrypt tells you the file was sealed to your public key, and nothing about who sealed it.
 
 
 ## Key Storage
@@ -223,11 +232,13 @@ Identity keys are stored in the user's home directory:
 
 ```
 ~/.noorm/
-├── identity.key     # X25519 private key (0600 permissions)
-├── identity.pub     # X25519 public key (0644 permissions)
-└── identity.json    # Metadata (name, email, machine, os)
+├── identity.key     # X25519 private key, hex PKCS8 DER (0600 permissions)
+├── identity.pub     # X25519 public key, hex SPKI DER (0644 permissions)
+└── identity.json    # Metadata: identityHash, name, email, publicKey, machine, os, createdAt
 ```
 
+`identityHash` is `SHA-256(email + '\0' + name + '\0' + machine + '\0' + os)` — the stable handle the database and the vault use to address a user.
+
 Identity is stored globally at `~/.noorm/`, separate from the project's encrypted state file (`.noorm/state/state.enc`). This separation means:
 - Identity works across all noorm projects on your machine
 - You can decrypt state files from any project with the same private key
@@ -238,22 +249,22 @@ Identity is stored globally at `~/.noorm/`, separate from the project's encrypte
 
 ### Export a config
 
-```bash
-# Export 'production' config for a teammate
-noorm config:export production
-# Enter their email when prompted
-# File created: production.noorm.enc
+```
+noorm ui  →  config list  →  +  →  [x] export
+# Pick 'production', enter the teammate's email
+# File created in the cwd: production.noorm.enc
 ```
 
 ### Import a config
 
-```bash
-# Import a shared config
-noorm config:import production.noorm.enc
-# Enter your database credentials when prompted
+```
+noorm ui  →  config list  →  +  →  [i] import
+# Select production.noorm.enc, enter your own database credentials
 # Config 'production' imported with your credentials
 ```
 
+There is no headless equivalent. `noorm config export|import` is the unencrypted JSON backup path described above, not this one.
+
 ### Known Users
 
 Before exporting, the recipient's public key must be known. Known users are discovered automatically when you activate a config:
@@ -263,7 +274,7 @@ Before exporting, the recipient's public key must be known. Known users are disc
 noorm config use production
 
 # Alice can now see Bob in her known users (if Bob has used this database)
-noorm identity known
+noorm identity list
 ```
 
 Identity sync happens automatically on `config use` - it registers your identity to the database and fetches other team members' public keys.
diff --git a/docs/dev/config.md b/docs/dev/config.md
index 583fa345..2013d3b2 100644
--- a/docs/dev/config.md
+++ b/docs/dev/config.md
@@ -49,21 +49,22 @@ interface Config {
         host?: string         // Required for non-SQLite, defaults to 'localhost'
         port?: number         // Default by dialect
         database: string      // Database name or file path
+        filename?: string     // SQLite only — alternative to database
         user?: string
         password?: string
         ssl?: boolean | SSLConfig
         pool?: { min?: number, max?: number }  // Defaults to { min: 0, max: 10 }
-    }
-
-    paths: {
-        schema: string        // Path to schema files
-        changes: string    // Path to change files
+        tlsServerName?: string  // MSSQL only — cert hostname when host is an IP
     }
 
     identity?: string         // Override audit identity
 }
 ```
 
+File locations (`paths.sql`, `paths.changes`) are **not** part of `Config` —
+they live in `settings.yml` and are read through `SettingsManager.getPaths()`.
+See [Settings](./settings.md).
+
 
 ## Environment Variables
 
@@ -87,10 +88,10 @@ NOORM_{PATH}_{TO}_{VALUE}  →  { path: { to: { value: '' } } }
 | `NOORM_CONNECTION_POOL_MIN` | `connection.pool.min` | |
 | `NOORM_CONNECTION_POOL_MAX` | `connection.pool.max` | |
 
-**Path variables:**
+**Path variables** (override `settings.yml` paths, not `Config`):
 
-| Variable | Config Path |
-|----------|-------------|
+| Variable | Settings Path |
+|----------|---------------|
 | `NOORM_PATHS_SQL` | `paths.sql` |
 | `NOORM_PATHS_CHANGES` | `paths.changes` |
 
@@ -106,12 +107,21 @@ NOORM_{PATH}_{TO}_{VALUE}  →  { path: { to: { value: '' } } }
 
 **Note:** For camelCase properties like `isTest`, preserve the case: `NOORM_isTest` (not `NOORM_IS_TEST`).
 
-**Behavior variables** (not merged into config):
+**Behavior variables** (excluded from config merging — the `META_ENV_VARS` set in `core/config`):
 
 | Variable | Purpose |
 |----------|---------|
 | `NOORM_CONFIG` | Which config to use |
 | `NOORM_YES` | Skip confirmations |
+| `NOORM_JSON` | JSON output mode |
+| `NOORM_HEADLESS` | Headless mode detection |
+| `NOORM_DEBUG` | Debug logging |
+| `NOORM_DEV` | Dev mode detection |
+| `NOORM_CI_CONFIG_NAME` | `ci init` config name override |
+| `NOORM_LOGGER_DEBUG` | Logger-internal debug |
+| `NOORM_CHANNEL` | Policy channel override (`resolveChannel`) |
+
+`NOORM_IDENTITY_*` is also excluded — it belongs to `loadIdentityFromEnv`, and forwarding it would collide with the `identity: string` field.
 
 ```bash
 # CI/CD example: use stored config with overridden host
@@ -280,15 +290,17 @@ stages:
 When resolving a config linked to a stage, stage defaults merge in:
 
 ```typescript
+import { resolveConfig, SettingsProvider } from './core/config/resolver'
+
 const config = resolveConfig(state, {
     name: 'prod',
-    stage: 'prod',  // Required when passing settings - must explicitly specify stage name
-    settings: settingsManager,
+    settings: new SettingsProvider(settingsManager),
+    // stage: 'prod',  // optional — omit to auto-link by matching config name
 })
 // Stage defaults applied, then stored config, then env, then flags
 ```
 
-> **Note:** When passing `settings`, you must also pass `stage` explicitly. Auto-detection of stage from config name is not yet implemented.
+> **Note:** `settings` takes a `SettingsProvider`, not a `SettingsManager` — wrap the manager. The class must be imported from `core/config/resolver` directly; the `core/config` barrel re-exports it type-only. When `stage` is omitted, `findStageForConfig` auto-links a stage whose name matches the config name.
 
 
 ## Config Completeness
@@ -298,10 +310,13 @@ A config is "complete" when all required secrets (from its stage) are set. Incom
 ```typescript
 import { checkConfigCompleteness } from './core/config'
 
-// With explicit stage name (recommended)
-const check = checkConfigCompleteness(config, state, settings, 'prod')
+// Fourth argument is an options object: { stageName?, vaultSecretKeys? }
+const check = checkConfigCompleteness(config, state, settings, {
+    stageName: 'prod',
+    vaultSecretKeys: ['DB_PASSWORD'],  // vault keys count as "set"
+})
 
-// Without stage name - only works if stage name matches config name exactly
+// Without stageName - auto-links a stage whose name matches the config name
 const check = checkConfigCompleteness(config, state, settings)
 
 if (!check.complete) {
diff --git a/docs/dev/datamodel.md b/docs/dev/datamodel.md
index a585506e..3d689ee9 100644
--- a/docs/dev/datamodel.md
+++ b/docs/dev/datamodel.md
@@ -20,11 +20,13 @@ State holds secrets and credentials. Settings holds team-shared rules. Database
 
 ```mermaid
 erDiagram
-    STATE ||--o| CRYPTO_IDENTITY : has
     STATE ||--o{ KNOWN_USER : contains
     STATE ||--o{ CONFIG : stores
     STATE ||--o{ SECRET : encrypts
 
+    KEY_FILES ||--|| CRYPTO_IDENTITY : holds
+    CRYPTO_IDENTITY ||--o{ KNOWN_USER : discovers
+
     CONFIG ||--|| CONNECTION_CONFIG : contains
     CONFIG ||--o{ SECRET : scoped_to
 
@@ -54,14 +56,16 @@ The encrypted state file at `.noorm/state/state.enc` contains all sensitive conf
 
 | Field | Type | Description |
 |-------|------|-------------|
-| version | string | noorm version for migrations |
-| identity | CryptoIdentity? | User's cryptographic identity |
-| knownUsers | Map | Known users discovered from databases |
-| activeConfig | string? | Currently selected config name |
+| version | string | Package version that last saved this state |
+| schemaVersion | number | State schema version, driving the `core/version/state` migrations |
+| knownUsers | Map | Known users discovered from databases (identityHash → KnownUser) |
+| activeConfig | string \| null | Currently selected config name |
 | configs | Map | Database configurations by name |
 | secrets | Map | Config-scoped secrets (configName → key → value) |
 | globalSecrets | Map | App-level secrets shared across configs |
 
+The cryptographic identity is **not** in state—it lives in `~/.noorm/` (see [Key Files](#key-files)). State migration v1 still writes a vestigial `identity: null` key onto older files; nothing reads it.
+
 
 ### Encrypted Payload
 
@@ -69,12 +73,13 @@ On-disk format for the state file.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| algorithm | string | Always `aes-256-gcm` |
+| algorithm | string | Always `aes-256-gcm`; rejected at decrypt if anything else |
+| kdf | string? | Key derivation used. Absent on payloads written before the field existed, which are `hkdf-sha256` by definition |
 | iv | string | Initialization vector (base64) |
 | authTag | string | Authentication tag (base64) |
 | ciphertext | string | Encrypted state JSON (base64) |
 
-The encryption key derives from machine-specific identifiers or the user's cryptographic identity passphrase.
+The AES key derives from the user's private key (`~/.noorm/identity.key`) via HKDF-SHA256. Recording `kdf` is what makes the derivation changeable later—without it, a build that changed the derivation would report every existing state file as "wrong key or corrupted".
 
 
 ---
@@ -94,18 +99,21 @@ A database connection profile stored in encrypted state.
 | isTest | boolean | Yes | Marks database as disposable for testing |
 | access | ConfigAccess | Yes | Per-channel access roles (`{ user, agent }`) — replaces the legacy `protected` boolean |
 | connection | ConnectionConfig | Yes | Database connection details |
-| paths | PathConfig | Yes | File system paths for schema and changes |
 | identity | string | No | Override identity for `executed_by` field |
 
+File system paths are **not** on the config—they come from settings (`paths.sql`, `paths.changes`; see [PathConfig](#pathconfig-settings)).
+
 
 ### ConfigAccess
 
-Per-channel access grant. `Role` is `'viewer' | 'operator' | 'admin'`.
+Per-channel access grant. `Role` is `'viewer' | 'operator' | 'admin'`; `Channel` is `'user' | 'agent'`.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| user | Role | Access for the CLI, TUI, and SDK |
-| mcp | Role \| `false` | Access for the MCP server. `false` hides the config entirely on this channel |
+| user | Role | A human at the keyboard—CLI, TUI, or SDK |
+| agent | Role \| `false` | An AI agent, whichever binary it reached for. `false` hides the config entirely on this channel |
+
+The channel describes *who is driving*, not which transport was used: an agent that shells out to the CLI after an MCP refusal is still `agent`. The field was named `mcp` until state migration v3 renamed it to `agent`.
 
 `checkPolicy(channel, config, permission)` resolves a `ConfigAccess` + `Permission` into `allow`/`confirm`/`deny`, channel-aware (`confirm` prompts on `user`, collapses to `deny` on `agent`). See `docs/spec/config-access-roles.md` for the full permission matrix.
 
@@ -123,8 +131,9 @@ Database connection parameters.
 | filename | string | SQLite | File path for SQLite databases |
 | user | string | No | Database username |
 | password | string | No | Database password |
-| ssl | boolean or object | No | SSL/TLS configuration |
+| ssl | boolean or object | No | SSL/TLS configuration (`rejectUnauthorized`, `ca`, `cert`, `key`) |
 | pool | object | No | Connection pool settings (`min`, `max`) |
+| tlsServerName | string | No | Hostname the server's TLS certificate is issued for. Needed only when `host` is an IP address, since SNI cannot carry an IP literal. MSSQL is the only dialect that reads it |
 
 **Default ports by dialect:**
 
@@ -136,19 +145,9 @@ Database connection parameters.
 | sqlite | N/A |
 
 
-### PathConfig
-
-File system paths for schema and changes.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| schema | string | Path to schema directory |
-| changes | string | Path to changes directory |
-
-
 ### ConfigSummary
 
-Lightweight config view for listings. Omits sensitive connection details.
+Lightweight config view for listings. Omits credentials.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -157,6 +156,8 @@ Lightweight config view for listings. Omits sensitive connection details.
 | isTest | boolean | Test database flag |
 | access | ConfigAccess | Per-channel access roles |
 | isActive | boolean | Currently selected config |
+| dialect | Dialect | `postgres`, `mysql`, `sqlite`, or `mssql` |
+| database | string | Database name |
 
 
 ### Config Resolution Order
@@ -246,12 +247,12 @@ Include acts as a filter, not an ordering mechanism. Files are executed in alpha
 
 ### PathConfig (Settings)
 
-Override default file locations.
+Override default file locations. This is the only place paths are configured—configs do not carry their own.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| schema | string | `schema` | Path to schema files |
-| changes | string | `changes` | Path to change directories |
+| sql | string | `./sql` | Path to SQL files |
+| changes | string | `./changes` | Path to change directories |
 
 
 ### Stage
@@ -301,6 +302,7 @@ Conditional file inclusion/exclusion based on config properties.
 
 | Field | Type | Description |
 |-------|------|-------------|
+| description | string? | Human-readable label (e.g. "test seeds") |
 | match | RuleMatch | Conditions that trigger this rule |
 | include | string[]? | Additional glob patterns to include |
 | exclude | string[]? | Additional glob patterns to exclude |
@@ -343,6 +345,21 @@ File logging configuration.
 | maxFiles | number | `5` | Maximum rotated files to keep |
 
 
+### TeardownConfig
+
+Controls database reset and teardown behavior. See [Teardown](/dev/teardown).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| preserveTables | string[]? | Tables always preserved during truncate operations |
+| postScript | string? | SQL script run after schema teardown (relative to project root) |
+
+
+### Universal Secrets
+
+Top-level `secrets: StageSecret[]` on the settings file declares secrets required by **all** stages, using the same [StageSecret](#stagesecret) shape.
+
+
 ---
 
 
@@ -418,10 +435,11 @@ Cryptographic keys are stored outside the project directory.
 ```
 ~/.noorm/
 ├── identity.key        # X25519 private key (hex, mode 600)
-└── identity.pub        # X25519 public key (hex, mode 644)
+├── identity.pub        # X25519 public key (hex, mode 644)
+└── identity.json       # CryptoIdentity metadata (name, email, machine, os, hash)
 ```
 
-The private key never leaves the user's machine. The public key is shared via database identity tables.
+The private key never leaves the user's machine. The public key is shared via database identity tables. The permission check on `identity.key` is a threat-model check, not strict equality—it passes when no group or other bits are set, so `0400` is accepted too.
 
 
 ---
@@ -445,21 +463,21 @@ Format for encrypted config export files (`*.noorm.enc`).
 | ciphertext | string | Encrypted config (hex) |
 
 
-### ExportedConfig
+### Exported Config Payload
 
-The decrypted contents of a shared config.
+The decrypted `ciphertext` is JSON of the shape `{ config, secrets }`. There is no named type for it—it is built inline in `src/tui/screens/config/ConfigExportScreen.tsx`.
 
 | Field | Type | Description |
 |-------|------|-------------|
-| name | string | Config name |
-| dialect | string | Database dialect |
-| connection | object | Host, port, database, ssl, pool (no user/password) |
-| paths | object | Schema and change directories |
-| isTest | boolean | Test database flag |
-| access | ConfigAccess | Per-channel access roles |
+| config.name | string | Config name |
+| config.type | enum | `local` or `remote` |
+| config.isTest | boolean | Test database flag |
+| config.access | ConfigAccess | Per-channel access roles |
+| config.protected | boolean | Compatibility echo of `guarded(config)`, so an older importer still makes a safe (if coarser) access decision |
+| config.connection | object | `dialect`, `host`, `port`, `database`, `ssl` only |
 | secrets | Map | Config-scoped secrets |
 
-**Note:** `user` and `password` are intentionally omitted. Recipients provide their own credentials on import.
+**Note:** `user` and `password` are intentionally omitted. Recipients provide their own credentials on import. `pool` and file system paths are not exported either.
 
 
 ---
@@ -467,7 +485,18 @@ The decrypted contents of a shared config.
 
 ## Database Tables
 
-noorm creates five tracking tables in the target database. All table names are prefixed with `__noorm_` to avoid conflicts.
+noorm creates six tracking tables in the target database, all in schema migration v1.
+
+Their names depend on the dialect. PostgreSQL and SQL Server get a dedicated `noorm` schema with clean names (`noorm.version`, `noorm.change`, and so on). MySQL and SQLite have no schemas, so they keep the `__noorm_*__` prefixed forms in the default schema, which is what the headings below use.
+
+Two column types are also dialect-dependent, and the tables below name the PostgreSQL form:
+
+| Doc type | postgres | mssql | mysql / sqlite |
+|----------|----------|-------|----------------|
+| serial (PK) | `serial` | `int identity(1,1)` | `integer` + `autoIncrement()` |
+| timestamp | `timestamp` | `datetime2` | `timestamp` |
+
+Every timestamp type here is **naive**—it stores a wall clock with no offset. Code writing these columns must serialize UTC and parse back as UTC, or two clients in different timezones will disagree about what an instant means. The postgres and mysql drivers bind and parse a JS `Date` using the client's local offset, so passing a `Date` straight through is what breaks; see `formatDateForDialect`/`parseDateFromDialect` in `src/core/lock/manager.ts`.
 
 
 ### `__noorm_version__`
@@ -481,10 +510,10 @@ Tracks noorm CLI version for internal schema migrations.
 | noorm_version | integer | NOT NULL | Tracking table schema version |
 | state_version | integer | NOT NULL | State file format version |
 | settings_version | integer | NOT NULL | Settings file format version |
-| installed_at | timestamp | NOT NULL, DEFAULT NOW() | First installation |
-| upgraded_at | timestamp | NOT NULL, DEFAULT NOW() | Last upgrade |
+| installed_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | First installation |
+| upgraded_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Last upgrade |
 
-This table tracks noorm's internal schema, not the user's database schema.
+This table tracks noorm's internal schema, not the user's database schema. It is append-only: every migration and version-record update inserts a new row, so `installed_at` comes from the first row and everything else from the latest.
 
 
 ### `__noorm_change__`
@@ -496,23 +525,27 @@ Tracks all operation batches—changes, builds, and ad-hoc runs.
 | id | serial | PK | Primary key |
 | name | varchar(255) | NOT NULL | Operation identifier |
 | change_type | varchar(50) | NOT NULL | `build`, `run`, or `change` |
-| direction | varchar(50) | NOT NULL | `change` or `revert` |
-| checksum | varchar(64) | NOT NULL | SHA-256 of sorted file checksums |
-| executed_at | timestamp | NOT NULL, DEFAULT NOW() | When executed |
-| executed_by | varchar(255) | NOT NULL | Identity string |
-| config_name | varchar(255) | NOT NULL | Which config was used |
-| cli_version | varchar(50) | NOT NULL | noorm version |
-| status | varchar(50) | NOT NULL | `pending`, `success`, `failed`, `reverted` |
-| error_message | text | NOT NULL | Error details (empty = no error) |
-| duration_ms | integer | NOT NULL | Execution time (0 = never ran) |
+| direction | varchar(50) | NOT NULL | `change` or `revert` (see note below) |
+| checksum | varchar(64) | NOT NULL, DEFAULT `''` | SHA-256 of sorted file checksums |
+| executed_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | When executed |
+| executed_by | varchar(255) | NOT NULL, DEFAULT `''` | Identity string |
+| config_name | varchar(255) | NOT NULL, DEFAULT `''` | Which config was used |
+| cli_version | varchar(50) | NOT NULL, DEFAULT `''` | noorm version |
+| status | varchar(50) | NOT NULL | `pending`, `success`, `failed`, `reverted`, `stale` |
+| error_message | varchar(2000) | NOT NULL, DEFAULT `''` | Error details (empty = no error) |
+| duration_ms | integer | NOT NULL, DEFAULT 0 | Execution time (0 = never ran) |
+
+**Index:** `idx_change_name_config` on (`name`, `config_name`).
+
+**Two `Direction` types exist.** The runner's in-memory `Direction` is `'commit' | 'revert'`; the column's is `'change' | 'revert'`. `Tracker` maps `commit` → `change` on write, so the database only ever holds `change` or `revert`. Query on those.
 
 **Name formats by change type:**
 
 | Change Type | Format | Example |
 |-------------|--------|---------|
-| change | Folder name | `2024-01-15_add-users` |
-| build | `build:{timestamp}` | `build:2024-01-15T10:30:00` |
-| run | `run:{timestamp}` | `run:2024-01-15T10:30:00` |
+| change | Folder name | `2024-01-15-add-users` |
+| build | `build:{ISO timestamp}` | `build:2024-01-15T10:30:00.000Z` |
+| run | `run:{ISO timestamp}` | `run:2024-01-15T10:30:00.000Z` |
 
 
 ### `__noorm_executions__`
@@ -522,15 +555,17 @@ Tracks individual file executions within an operation.
 | Column | Type | Constraints | Description |
 |--------|------|-------------|-------------|
 | id | serial | PK | Primary key |
-| change_id | integer | FK, NOT NULL | Parent operation |
+| change_id | integer | FK → change(id) ON DELETE CASCADE, NOT NULL | Parent operation |
 | filepath | varchar(500) | NOT NULL | Executed file path |
 | file_type | varchar(10) | NOT NULL | `sql` or `txt` |
-| checksum | varchar(64) | NOT NULL | SHA-256 of file contents |
-| cli_version | varchar(50) | NOT NULL | noorm version |
+| checksum | varchar(64) | NOT NULL, DEFAULT `''` | SHA-256 of file contents |
+| cli_version | varchar(50) | NOT NULL, DEFAULT `''` | noorm version |
 | status | varchar(50) | NOT NULL | `pending`, `success`, `failed`, `skipped` |
-| error_message | text | NOT NULL | Error details (empty = no error) |
-| skip_reason | varchar(100) | NOT NULL | Why skipped (empty = not skipped) |
-| duration_ms | integer | NOT NULL | Execution time (0 = never ran) |
+| error_message | varchar(2000) | NOT NULL, DEFAULT `''` | Error details (empty = no error) |
+| skip_reason | varchar(100) | NOT NULL, DEFAULT `''` | Why skipped (empty = not skipped); truncated to 100 chars on write |
+| duration_ms | integer | NOT NULL, DEFAULT 0 | Execution time (0 = never ran) |
+
+**Index:** `idx_executions_change_id` on (`change_id`).
 
 
 ### `__noorm_lock__`
@@ -542,9 +577,9 @@ Prevents concurrent operations on the same database.
 | id | serial | PK | Primary key |
 | config_name | varchar(255) | UNIQUE, NOT NULL | Lock scope |
 | locked_by | varchar(255) | NOT NULL | Identity of holder |
-| locked_at | timestamp | NOT NULL, DEFAULT NOW() | When acquired |
+| locked_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | When acquired |
 | expires_at | timestamp | NOT NULL | Auto-expiry time |
-| reason | varchar(255) | NOT NULL | Lock reason (empty = none) |
+| reason | varchar(255) | NOT NULL, DEFAULT `''` | Lock reason (empty = none) |
 
 Locks automatically expire to prevent deadlocks from crashed processes.
 
@@ -562,10 +597,27 @@ Stores user identities for team discovery.
 | machine | varchar(255) | NOT NULL | Machine hostname |
 | os | varchar(255) | NOT NULL | OS platform and version |
 | public_key | text | NOT NULL | X25519 public key (hex) |
-| registered_at | timestamp | NOT NULL, DEFAULT NOW() | First registration |
-| last_seen_at | timestamp | NOT NULL, DEFAULT NOW() | Last activity |
+| encrypted_vault_key | text | NULL | Vault key encrypted with this user's public key. NULL for users without vault access |
+| registered_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | First registration |
+| last_seen_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | Last activity |
+
+Auto-populated on first database connection when cryptographic identity is configured. `encrypted_vault_key` is the only nullable column in any tracking table.
+
 
-Auto-populated on first database connection when cryptographic identity is configured.
+### `__noorm_vault__`
+
+Team-shared secrets, encrypted with a vault key distributed via each member's public key. Full lifecycle in [Vault](/dev/vault).
+
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | serial | PK | Primary key |
+| secret_key | varchar(255) | UNIQUE, NOT NULL | Secret key name (e.g. `API_KEY`) |
+| encrypted_value | text | NOT NULL | AES-256-GCM encrypted value, JSON `{iv, authTag, ciphertext}` |
+| set_by | varchar(255) | NOT NULL | Identity that set this secret |
+| created_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | When created |
+| updated_at | timestamp | NOT NULL, DEFAULT CURRENT_TIMESTAMP | When last updated |
+
+**Index:** `idx_vault_secret_key` on (`secret_key`).
 
 
 ---
@@ -580,7 +632,7 @@ Changes live on disk as directories with a specific structure.
 
 ```
 changes/
-└── 2024-01-15_add-email-verification/
+└── 2024-01-15-add-email-verification/
     ├── change/
     │   ├── 001_add-column.sql
     │   ├── 002_update-data.sql
@@ -598,9 +650,9 @@ When read from disk, changes are parsed into:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| name | string | Folder name (e.g., `2024-01-15_add-email-verification`) |
+| name | string | Folder name (e.g., `2024-01-15-add-email-verification`) |
 | path | string | Absolute path to directory |
-| date | Date? | Parsed from name prefix (YYYY-MM-DD) |
+| date | Date \| null | Parsed from name prefix (YYYY-MM-DD), null if no date prefix |
 | description | string | Human-readable, derived from name |
 | changeFiles | ChangeFile[] | Files in `change/` subdirectory |
 | revertFiles | ChangeFile[] | Files in `revert/` subdirectory |
@@ -633,15 +685,17 @@ Individual file within a change.
 Change folder names follow a convention:
 
 ```
-{date}_{description}
+{date}-{description}
 ```
 
 | Component | Format | Example |
 |-----------|--------|---------|
 | date | `YYYY-MM-DD` | `2024-01-15` |
-| description | kebab-case | `add-email-verification` |
+| description | kebab-case (slugified) | `add-email-verification` |
+
+The date prefix ensures chronological ordering. The description provides context. The separator is a hyphen, matching the date's own separators—the parser's prefix regex is `/^(\d{4}-\d{2}-\d{2})-(.+)$/`.
 
-The date prefix ensures chronological ordering. The description provides context.
+Files *inside* `change/` and `revert/` use a different convention: `{sequence}_{slug}.{ext}`, with an underscore (e.g. `001_add-column.sql`).
 
 
 ---
@@ -660,6 +714,7 @@ Used in `__noorm_change__` and change results.
 | success | Completed successfully |
 | failed | Execution failed |
 | reverted | Was applied, then rolled back |
+| stale | Schema objects were torn down; needs re-run |
 
 
 ### Execution Status
@@ -676,11 +731,15 @@ Used in `__noorm_executions__` and file results.
 
 ### Skip Reasons
 
+Free-form text, not an enum. The values emitted today:
+
 | Reason | Meaning |
 |--------|---------|
 | unchanged | File checksum matches previous run |
 | already-run | File was already executed successfully |
-| change failed | Parent change failed |
+| already applied | The change as a whole was already applied |
+| change failed | Parent change failed with no single culprit file |
+| `{file} failed: {error}` | Parent change failed at a named file; remaining files skipped |
 
 
 ### Lock
@@ -701,6 +760,7 @@ Options for lock acquisition.
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
+| dialect | enum | `postgres` | Dialect, used to pick the date format written to `locked_at`/`expires_at` |
 | timeout | number | 300,000 (5 min) | Lock duration in ms |
 | wait | boolean | false | Block until available |
 | waitTimeout | number | 30,000 (30 sec) | Maximum wait time in ms |
@@ -717,9 +777,9 @@ Options for file execution.
 | force | boolean | false | Re-run even if unchanged |
 | concurrency | number | 1 | Parallel file execution |
 | abortOnError | boolean | true | Stop on first failure |
-| dryRun | boolean | false | Render to temp without executing |
-| preview | boolean | false | Output SQL without executing |
-| output | string? | — | Write rendered SQL to file |
+| dryRun | boolean | false | Report what would run without executing |
+| preview | boolean | false | Output rendered SQL without executing |
+| output | string \| null | null | Write preview output to file instead of stdout |
 
 **Note:** Concurrency defaults to 1 (sequential) because DDL operations often cannot run in parallel.
 
@@ -736,8 +796,8 @@ Available in `.sql.tmpl` templates via Eta.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `$.<filename>` | any | Auto-loaded data from co-located files |
-| `$.config` | object | Active config values |
+| `$.<filename>` | any | Auto-loaded data from co-located files (key is the camelCased filename) |
+| `$.config` | object? | Active config values. Present only when no `config.*` data file exists in the template directory—a co-located file wins |
 | `$.secrets` | Map | Config-scoped secrets |
 | `$.globalSecrets` | Map | App-level secrets |
 | `$.env` | Map | Environment variables |
@@ -761,11 +821,14 @@ Files co-located with templates are automatically loaded.
 
 | Extension | Loader | Result |
 |-----------|--------|--------|
-| .json, .json5 | JSON parser | Object |
+| .json, .json5 | JSON5 parser | Object |
 | .yaml, .yml | YAML parser | Object |
 | .csv | CSV parser | Array of objects |
 | .js, .mjs, .ts | Dynamic import | Default export |
 | .sql | File read | String |
+| .dt, .dtz | DT deserializer | Array of rows |
+
+`.dtzx` is deliberately absent—there is no way to supply its passphrase from template context. The `.js`/`.mjs`/`.ts` loaders *execute* the file; the rest only parse.
 
 Data files are available on `$` by filename without extension:
 
@@ -800,10 +863,12 @@ Each layer has independent migrations that run automatically when version mismat
 
 | Layer | Current Version |
 |-------|-----------------|
-| schema | 1 |
-| state | 1 |
+| schema | 2 |
+| state | 3 |
 | settings | 1 |
 
+Source of truth: `CURRENT_VERSIONS` in `src/core/version/types.ts`. See [Version](/dev/version).
+
 
 ---
 
@@ -1029,7 +1094,7 @@ noorm's data model spans three tiers with clear separation of concerns:
 
 1. **Encrypted State** - Secrets, credentials, configs (`.noorm/state/state.enc`)
 2. **Settings** - Team rules, stages, build config (`.noorm/settings.yml`)
-3. **Database Tables** - Execution history, locks, identities (`__noorm_*`)
+3. **Database Tables** - Execution history, locks, identities, vault (`noorm.*` on postgres/mssql, `__noorm_*__` on mysql/sqlite)
 
 The change file system provides versioned changes, while runtime types enable flexible execution modes (dry run, preview, force).
 
diff --git a/docs/dev/explore.md b/docs/dev/explore.md
index 232df74e..c167e520 100644
--- a/docs/dev/explore.md
+++ b/docs/dev/explore.md
@@ -7,7 +7,7 @@ You've run your schema builds and changes. The database says "success." But did
 
 Connecting via pgAdmin, MySQL Workbench, or Azure Data Studio works, but it breaks your flow. You're in the terminal. You want to stay there.
 
-noorm's explore module gives you read-only schema introspection directly from the CLI. Browse tables, views, procedures, functions, types, indexes, and foreign keys across PostgreSQL, MySQL, MSSQL, and SQLite—all without leaving your workflow.
+noorm's explore module gives you read-only schema introspection directly from the CLI. Browse tables, views, procedures, functions, types, indexes, foreign keys, triggers, locks, and connections across PostgreSQL, MySQL, MSSQL, and SQLite—all without leaving your workflow.
 
 
 ## How It Works
@@ -56,7 +56,7 @@ if (detail) {
 
 ## Object Categories
 
-Seven categories of database objects can be explored:
+Ten categories of database objects can be explored (`ExploreCategory` in `src/core/explore/types.ts:12`):
 
 | Category | Summary Info | Detail Info |
 |----------|--------------|-------------|
@@ -67,6 +67,11 @@ Seven categories of database objects can be explored:
 | `types` | Kind (enum/composite/domain), value count | Values, attributes, base type |
 | `indexes` | Table, columns, unique/primary flags | — (list only) |
 | `foreignKeys` | Source → target table, columns | — (list only) |
+| `triggers` | Table, timing, events | Timing, events, definition, enabled flag |
+| `locks` | PID, lock type, mode, granted flag | — (list only) |
+| `connections` | PID, user, database, state | — (list only) |
+
+`locks` and `connections` describe the live server session, not the schema. They take no `schema` filter — `listLocks(db)` / `listConnections(db)` are the only dialect methods without one.
 
 
 ## Overview
@@ -83,16 +88,29 @@ const overview = await fetchOverview(db, 'postgres')
 //     functions: 12,
 //     types: 8,
 //     indexes: 47,
-//     foreignKeys: 18
+//     foreignKeys: 18,
+//     triggers: 4,
+//     locks: 2,
+//     connections: 6
 // }
 ```
 
+Counts come from the same list calls the detail views use, so the overview can never disagree with what drilling in shows.
+
 By default, noorm internal tables (`__noorm_*`) are excluded from counts. Include them with:
 
 ```typescript
 const overview = await fetchOverview(db, 'postgres', { includeNoormTables: true })
 ```
 
+`includeNoormTables` only affects the prefixed `__noorm_*` names used on MySQL and SQLite. On PostgreSQL and SQL Server the tracking tables live in a dedicated `noorm` schema, which every dialect query excludes outright — the flag cannot bring them back.
+
+Both `fetchOverview` and `fetchList` also accept `schema` to narrow results to one schema. It reaches the generated SQL rather than filtering afterwards, and it throws on SQLite, which has no schemas.
+
+```typescript
+const overview = await fetchOverview(db, 'postgres', { schema: 'reporting' })
+```
+
 
 ## Lists
 
@@ -208,7 +226,9 @@ interface FunctionSummary {
 
 interface IndexSummary {
     name: string
+    schema?: string
     tableName: string
+    tableSchema?: string
     columns: string[]
     isUnique: boolean
     isPrimary: boolean
@@ -216,13 +236,25 @@ interface IndexSummary {
 
 interface ForeignKeySummary {
     name: string
+    schema?: string
     tableName: string
+    tableSchema?: string
     columns: string[]
     referencedTable: string
+    referencedSchema?: string
     referencedColumns: string[]
     onDelete?: string
     onUpdate?: string
 }
+
+interface TriggerSummary {
+    name: string
+    schema?: string
+    tableName: string
+    tableSchema?: string
+    timing: 'BEFORE' | 'AFTER' | 'INSTEAD OF'
+    events: ('INSERT' | 'UPDATE' | 'DELETE')[]
+}
 ```
 
 ### Detail Types
@@ -276,7 +308,7 @@ formatSummaryDescription('indexes', { name: 'idx', tableName: 'users', isPrimary
 
 ## Dialect Support
 
-All seven categories work across supported dialects with appropriate translations:
+Categories translate per dialect; unsupported ones return an empty array rather than throwing:
 
 | Feature | PostgreSQL | MySQL | MSSQL | SQLite |
 |---------|------------|-------|-------|--------|
@@ -287,8 +319,11 @@ All seven categories work across supported dialects with appropriate translation
 | Types | ✓ (enum, composite, domain) | — | ✓ (alias, table types) | — |
 | Indexes | ✓ | ✓ | ✓ | ✓ |
 | Foreign Keys | ✓ | ✓ | ✓ | ✓ |
+| Triggers | ✓ | ✓ | ✓ | ✓ |
+| Locks | ✓ | ✓ (`performance_schema`) | ✓ | — |
+| Connections | ✓ | ✓ | ✓ | — |
 
-SQLite doesn't support stored procedures, functions, or user-defined types. MySQL doesn't support user-defined types. These categories return empty arrays for unsupported dialects.
+SQLite doesn't support stored procedures, functions, or user-defined types, and has no server-side lock or connection views. MySQL doesn't support user-defined types, and its lock listing needs `SELECT` on `performance_schema` — without the grant it degrades to an empty list rather than failing the call.
 
 
 ## CLI Integration
@@ -306,7 +341,7 @@ Keyboard shortcuts:
 
 | Key | Action |
 |-----|--------|
-| `e` | Enter explore mode |
+| `x` | Enter explore mode (from the database screen) |
 | `↑/↓` | Navigate lists |
 | `Enter` | View detail |
 | `Esc` | Go back |
diff --git a/docs/dev/headless.md b/docs/dev/headless.md
index d0bff6b6..67499a55 100644
--- a/docs/dev/headless.md
+++ b/docs/dev/headless.md
@@ -28,10 +28,27 @@ Internally, the CLI is built on [citty](https://github.com/unjs/citty). Each com
 
 Not every command accepts every flag — append `--help` to any command to see the exact surface.
 
+Every flag in that table belongs to a *subcommand* and must appear after it. The
+one flag with a root-level meaning is `--cwd`:
+
+| Flag | Short | Type | Description |
+|------|-------|------|-------------|
+| `--cwd` | `-c` | string | Run the subcommand in `<path>`. Must precede the subcommand, like `git -C`. |
+
+`-c` is therefore overloaded by position: `noorm -c prod change ff` chdirs into
+`./prod`, while `noorm change ff -c prod` selects the `prod` config. Any *other*
+flag placed before the subcommand is rejected with a usage error rather than
+silently dropped — citty forwards only the argv after the subcommand index, so a
+hoisted flag would never reach the command's parser. `--help`/`-h` and
+`--version`/`-v` are exempt from that rejection at any position: `entry()` scans
+argv for `--help`/`-h` itself, and citty's `runMain` handles a bare `--version`
+before dispatch.
+
 **Example:**
 ```bash
 noorm change ff --config prod --json
 noorm change ff --help       # Per-command help, rendered by citty
+noorm -c ./services/api change ff   # run against a different project root
 ```
 
 
@@ -126,7 +143,9 @@ noorm run build --force  # Skip checksums
 **JSON output:**
 ```json
 {
+    "success": true,
     "status": "success",
+    "files": [],
     "filesRun": 5,
     "filesSkipped": 2,
     "filesFailed": 0,
@@ -134,6 +153,11 @@ noorm run build --force  # Skip checksums
 }
 ```
 
+Every `--json` payload is an object carrying a top-level boolean `success`, added
+by `toJsonEnvelope` in `src/cli/_utils.ts` — never a bare array — so `jq -e
+'.success'` works against any command. When the payload carries a core `status`
+string, `success` is derived from it (`partial` is never reported as `true`).
+
 #### `run file`
 
 Execute a single SQL file.
@@ -145,7 +169,9 @@ noorm run file sql/01_tables/001_users.sql
 **JSON output:**
 ```json
 {
-    "filepath": "sql/01_tables/001_users.sql",
+    "success": true,
+    "filepath": "/abs/path/sql/01_tables/001_users.sql",
+    "checksum": "e3b0c442...",
     "status": "success",
     "durationMs": 45
 }
@@ -172,10 +198,14 @@ noorm change list
 
 **JSON output:**
 ```json
-[
-    { "name": "001_init", "status": "success" },
-    { "name": "002_users", "status": "pending" }
-]
+{
+    "success": true,
+    "changes": [
+        { "name": "001_init", "status": "success" },
+        { "name": "002_users", "status": "pending" }
+    ],
+    "pending": 1
+}
 ```
 
 #### `change ff`
@@ -189,6 +219,7 @@ noorm change ff
 **JSON output:**
 ```json
 {
+    "success": true,
     "status": "success",
     "executed": 3,
     "skipped": 0,
@@ -202,11 +233,11 @@ noorm change ff
 
 #### `change run`
 
-Apply a specific change.
+Apply a specific change. The name is a positional argument; omit it on a TTY to
+pick interactively.
 
 ```bash
 noorm change run 001_init
-noorm --name 001_init change run
 ```
 
 #### `change revert`
@@ -223,7 +254,7 @@ Get execution history.
 
 ```bash
 noorm change history
-noorm --count 50 change history  # Last 50 records
+noorm change history --count 50  # Last 50 records (default: 20)
 ```
 
 
@@ -240,7 +271,9 @@ noorm db truncate
 **JSON output:**
 ```json
 {
+    "success": true,
     "truncated": ["users", "posts", "comments"],
+    "preserved": [],
     "count": 3
 }
 ```
@@ -253,16 +286,21 @@ Drop all database objects (except noorm tracking tables).
 noorm db teardown
 ```
 
-**JSON output:**
+**JSON output:** `dropped` holds object *names* per category, not counts.
+`count` is the total across `tables`, `views`, `functions`, and `types`.
+
 ```json
 {
+    "success": true,
     "dropped": {
-        "tables": 5,
-        "views": 2,
-        "functions": 3,
-        "types": 1
+        "tables": ["users", "posts"],
+        "views": ["active_users"],
+        "functions": [],
+        "procedures": [],
+        "types": [],
+        "foreignKeys": []
     },
-    "count": 11
+    "count": 3
 }
 ```
 
@@ -280,11 +318,17 @@ noorm db explore
 **JSON output:**
 ```json
 {
+    "success": true,
     "tables": 12,
     "views": 3,
-    "functions": 5,
     "procedures": 0,
-    "types": 2
+    "functions": 5,
+    "types": 2,
+    "indexes": 18,
+    "foreignKeys": 7,
+    "triggers": 0,
+    "locks": 0,
+    "connections": 4
 }
 ```
 
@@ -298,23 +342,27 @@ noorm db explore tables
 
 **JSON output:**
 ```json
-[
-    { "name": "users", "columnCount": 8 },
-    { "name": "posts", "columnCount": 5 }
-]
+{
+    "success": true,
+    "tables": [
+        { "name": "users", "columnCount": 8 },
+        { "name": "posts", "columnCount": 5 }
+    ]
+}
 ```
 
 #### `db explore tables detail`
 
-Describe a specific table.
+Describe a specific table. The table name is a positional argument.
 
 ```bash
-noorm --name users db explore tables detail
+noorm db explore tables detail users
 ```
 
 **JSON output:**
 ```json
 {
+    "success": true,
     "name": "users",
     "schema": "public",
     "columns": [
@@ -338,6 +386,7 @@ noorm lock status
 **JSON output:**
 ```json
 {
+    "success": true,
     "isLocked": true,
     "lock": {
         "lockedBy": "deploy@ci-runner",
@@ -437,7 +486,7 @@ jobs:
               run: noorm change ff
 
             - name: Export schema (optional)
-              run: noorm -c prod db explore --json > schema.json
+              run: noorm db explore -c prod --json > schema.json
 ```
 
 
@@ -480,12 +529,13 @@ set -e
 
 CONFIG="${1:-}"  # Optional, falls back to active config
 
+# The flag goes AFTER the subcommand — before it, -c means --cwd.
 echo "Checking for pending changes..."
-PENDING=$(noorm ${CONFIG:+-c "$CONFIG"} change list --json | jq '.pending')
+PENDING=$(noorm change list --json ${CONFIG:+-c "$CONFIG"} | jq '.pending')
 
 if [ "$PENDING" -gt 0 ]; then
     echo "Applying $PENDING pending changes..."
-    noorm ${CONFIG:+-c "$CONFIG"} change ff
+    noorm change ff ${CONFIG:+-c "$CONFIG"}
 else
     echo "Database is up to date"
 fi
@@ -564,12 +614,22 @@ noorm db explore tables detail users
 # Positional arguments come last; flags can appear anywhere after
 # the leaf command (citty parses options per-subcommand).
 noorm change ff --dry-run
-noorm vault cp --all staging production
+noorm vault cp API_KEY staging production
 noorm db transfer --to backup --tables users,posts
+
+# Rejected: only -c/--cwd is recognized before the subcommand.
+noorm --json change ff   # Error: Unrecognized flag '--json' before the subcommand
 ```
 
 There is no colon or slash syntax — the old `change:ff` / `change/ff` notation was a meow-era artifact and is gone.
 
+One argv rewrite happens before citty sees it: `noorm sql "SELECT 1"` becomes
+`noorm sql query "SELECT 1"`. `sql` has real subcommands (`query`, `history`,
+`clear`, `repl`), so citty would otherwise read the SQL string as a subcommand
+name. `rewriteBareSqlArgv` in `src/cli/index.ts` only rewrites when the first
+positional after `sql` starts with a known SQL verb, so the explicit subcommands
+are untouched.
+
 
 ## Adding New Commands
 
@@ -581,21 +641,31 @@ Each command is a self-contained citty `defineCommand` module. Domains map to di
 ```
 src/cli/
 ├── _utils.ts             # withContext, withVaultContext, sharedArgs, output helpers
-├── index.ts              # Root command + --help interceptor
+├── _exit.ts              # EXIT codes + exitCodeForStatus / isSuccessStatus
+├── index.ts              # Root command, argv preprocessing, --help interceptor
 ├── ui.ts                 # Lazy-imports the TUI
+├── info.ts               # `noorm info` (leaf command at the root)
 ├── change/
-│   ├── index.ts          # `noorm change` parent (subCommands + run handler)
+│   ├── index.ts          # `noorm change` parent (subCommands only, no run handler)
 │   ├── ff.ts             # `noorm change ff`
 │   ├── run.ts            # `noorm change run`
 │   └── ...
+├── ci/
 ├── config/
 ├── db/
+├── dev/
+├── identity/
 ├── lock/
+├── mcp/
 ├── run/
-├── vault/
-└── mcp/
+├── secret/
+├── settings/
+├── sql/
+└── vault/
 ```
 
+Root subcommands are registered as lazy thunks (`() => import('./change/index.js').then(m => m.default)`) so a single invocation only loads the domain it dispatches to. `resolveCommand` walks argv one positional at a time and resolves thunks as it goes; `printHelpWithExamples` rebuilds the full USAGE breadcrumb from the walked chain, because citty's `renderUsage` only concatenates one level.
+
 
 ### Command Module Pattern
 
@@ -604,9 +674,9 @@ Each leaf command exports a citty `defineCommand` and (optionally) an `examples:
 ```typescript
 // src/cli/change/ff.ts
 import { defineCommand } from 'citty';
-import { attempt } from '@logosdx/utils';
 
 import { sharedArgs, withContext, outputResult } from '../_utils.js';
+import { exitCodeForStatus } from '../_exit.js';
 
 const command = defineCommand({
     meta: {
@@ -626,14 +696,20 @@ const command = defineCommand({
 
                 if (!args.json) logger.info('Applying pending changes...');
 
-                return ctx.noorm.changes.ff({ dryRun: args.dryRun });
+                return ctx.noorm.changes.ff({
+                    dryRun: Boolean(args.dryRun),
+                    force: Boolean(args.force),
+                });
 
             },
         });
 
         if (err) process.exit(1);
 
-        outputResult(args, result, `Applied ${result.applied} changes`);
+        outputResult(args, result, `Executed ${result.executed} changes`);
+
+        // Never a bare process.exit(0): 'partial' must exit 3, not 0.
+        process.exit(exitCodeForStatus(result.status));
 
     },
 });
@@ -651,10 +727,11 @@ export default command;
 Key details:
 
 - **`sharedArgs`** lives in `src/cli/_utils.ts` and supplies the conventional `--config`, `--json`, `--force`, `--dry-run`, `--yes` set. Spread it first, then add your own.
-- **`withContext`** owns the SDK lifecycle (`createContext` → `connect` → `ensureSchemaVersion` → run → `disconnect`) and returns an `[result, error]` tuple. It also creates a logger configured for JSON or text output.
+- **`withContext`** owns the SDK lifecycle (`createContext` → `connect` → `ensureSchemaVersion` → run → `disconnect`) and returns an `[result, error]` tuple. It also creates a logger configured for JSON or text output. It derives two `createContext` options the command never passes itself: `yes` from `isYesMode(args)` (`--yes` or `NOORM_YES`), and `channel` from `resolveChannel()` — so a command run inside an agent harness is policy-checked on the `agent` channel without every leaf opting in.
 - **Logger guards** — when `args.json` is true, only structured JSON should reach stdout. Wrap any human progress output in `if (!args.json) { ... }` so callers piping JSON downstream get clean output.
-- **`outputResult`** routes its first arg to `logger.result(json)` in `--json` mode and to `logger.info(text)` in human mode.
+- **`outputResult(args, json, text, logger?)`** emits to stdout in both modes. In `--json` mode the payload goes through `toJsonEnvelope` (adds the `success` flag) and out via `logger.result()` when a logger is supplied. In human mode the text is written to `process.stdout` **directly**, never through `logger.info` — the logger's event stream goes to stderr, and a command's result must not land there.
 - **`examples`** is post-assigned via a typed cast because citty's `CommandDef` type does not include the field. The root `--help` interceptor reads it and renders an `EXAMPLES` block.
+- **Exit codes** come from `src/cli/_exit.ts`: `exitCodeForStatus(status)` maps `success`/`skipped` → 0, `partial` → 3, everything else → 1. Use `EXIT.USAGE` (2) for a bad invocation or a named target that does not exist.
 
 
 ### Parent Commands
@@ -693,7 +770,7 @@ Status listing previously lived on the bare `change` handler -- it was moved to
 
 ### TUI-Only Wizards
 
-Some commands (`config add`, `config edit`) don't have a sensible headless equivalent — they exist to walk users through credential entry interactively. Rather than importing the TUI, they print `Interactive only — run: noorm ui` to stderr and exit 1, leaving the user to launch the TUI themselves. See `src/cli/config/add.ts` for the canonical pattern.
+Some commands (`config add`, `config edit`) don't have a sensible headless equivalent — they exist to walk users through credential entry interactively. Rather than importing the TUI, they call `outputError` (stderr in human mode, a `{ success: false, error }` object under `--json`) and exit 1, leaving the user to launch the TUI themselves. `config add` also names its headless escape hatch in the message: `Interactive only — run: noorm ui. For headless creation use: noorm config import <file.json>`. See `src/cli/config/add.ts` for the canonical pattern.
 
 `config rm` used to live in this bucket but is now real and headless: bootstrap state (`initState`/`getStateManager`), gate the deletion through `checkConfigPolicy` (denies or requires `--yes`/`NOORM_YES` per the config's `user`-channel role for `config:rm`), then call `StateManager.deleteConfig()` — the same core path the TUI's removal screen uses, so the locked-stage guard applies identically. See `src/cli/config/rm.ts`.
 
@@ -741,19 +818,22 @@ describe('cli: change ff', () => {
 
         const result = await noorm(project, 'change', 'ff');
         expect(result.exitCode).toBe(0);
-        expect(result.stdout).toContain('Applied');
+        expect(result.stdout).toContain('Fast-forward success');
 
     });
 
     it('emits structured JSON with --json', async () => {
 
-        const result = await noormJson<{ applied: number }>(project, 'change', 'ff');
+        const result = await noormJson<{ success: boolean; executed: number }>(
+            project, 'change', 'ff',
+        );
         expect(result.ok).toBe(true);
-        expect(result.data?.applied).toBeGreaterThanOrEqual(0);
+        expect(result.data?.success).toBe(true);
+        expect(result.data?.executed).toBeGreaterThanOrEqual(0);
 
     });
 
 });
 ```
 
-The setup helper builds an isolated SQLite project and runs the compiled CLI via `node packages/cli/dist/index.js`. `noormJson` automatically appends `--json` after the command path (citty parses flags per-subcommand, so it must come last).
+The setup helper builds an isolated SQLite project (env-only mode, no `state.enc`) and runs the compiled CLI via `node dist/cli/index.js`. `noormJson` automatically appends `--json` after the command path (citty parses flags per-subcommand, so it must come last) and returns `{ data, error, exitCode, ok }` — `ok` is the process outcome, `data.success` is the payload's own flag.
diff --git a/docs/dev/identity.md b/docs/dev/identity.md
index 8957e977..0c507e91 100644
--- a/docs/dev/identity.md
+++ b/docs/dev/identity.md
@@ -22,6 +22,12 @@ Every database operation records who performed it. This identity comes from mult
 
 The resolver tries each source until it finds a valid name. This means zero configuration for most users—git config "just works."
 
+Two env vars are in play and they are not the same thing. `NOORM_IDENTITY` is the
+plain audit string at priority 3. The `NOORM_IDENTITY_*` trio
+(see [Env-Var Identity Override](#env-var-identity-override-ci)) reconstructs a full
+crypto identity that `getIdentityForConfig` reads through `getIdentityOverride()`,
+which lands it at priority **2** — so when both are set, `NOORM_IDENTITY_*` wins.
+
 ```typescript
 import { resolveIdentity } from './core/identity'
 
@@ -244,7 +250,7 @@ This loads your existing public key from `~/.noorm/identity.pub` and creates the
 
 When you activate a database config (`noorm config use <name>`), noorm automatically syncs identities:
 
-1. Registers your identity to the database's `__noorm_identities__` table
+1. Registers your identity to the identities table (`__noorm_identities__` on MySQL and SQLite, `noorm.identities` on PostgreSQL and SQL Server)
 2. Fetches other team members' identities from the database
 3. Caches discovered users locally as "known users"
 
@@ -253,28 +259,80 @@ This happens silently and non-blocking—connection failures don't prevent confi
 ```typescript
 import { syncIdentityWithConfig } from './core/identity'
 
-// Sync returns known users instead of storing them directly
-const result = await syncIdentityWithConfig(config, cryptoIdentity)
+// Takes the config only — it loads the identity itself from ~/.noorm/.
+// Returns known users instead of storing them directly.
+const result = await syncIdentityWithConfig(config)
 
-if (result.success) {
+if (result.ok && result.knownUsers?.length) {
     // Store discovered users in state
     await stateManager.addKnownUsers(result.knownUsers)
 }
 ```
 
 The sync function:
-- Connects to the database
+- Loads the crypto identity from `~/.noorm/` (returns `{ ok: true, knownUsersCount: 0 }` if there is none)
+- Derives the dialect from `config.connection.dialect` — callers do not pass it
+- Connects to the database (a connection failure is non-blocking: it emits an error event and returns `ok: true` with no users)
+- Runs `ensureSchemaVersion` so a database still on the legacy prefixed tables is migrated before identity queries hit `noorm.identities`
 - Checks if noorm tracking tables exist (skips sync if not bootstrapped)
 - Upserts your identity (updates `last_seen_at` if already registered)
-- Fetches all identities from the table
-- Returns the list of known users
+- Fetches all identities from the table, but only when the count is non-zero
+- Returns `IdentitySyncResult`: `{ ok, error?, registered?, knownUsersCount?, knownUsers? }`
+
+Note the result flag is `ok`, not `success` — and `ok: true` does not mean the sync
+reached the database. It means nothing went wrong that should block config
+activation, which includes the "could not connect" and "no identity" paths.
 
 **Observer events:**
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `identity:registered` | `{ identityHash, configName }` | Your identity added to database |
-| `identity:synced` | `{ configName, usersDiscovered }` | Sync completed |
+| `identity:registered` | `{ identityHash, name, email }` | Your identity inserted into the database (not emitted on a `last_seen_at` update) |
+| `identity:synced` | `{ configName, registered, knownUsersCount }` | Sync completed |
+
+
+## Env-Var Identity Override (CI)
+
+A CI runner has no `~/.noorm/`, so identity comes from environment variables
+instead. `loadIdentityFromEnv()` reads three vars and reconstructs a full
+`CryptoIdentity` without touching the filesystem:
+
+| Variable | Description |
+|----------|-------------|
+| `NOORM_IDENTITY_PRIVATE_KEY` | X25519 private key, hex PKCS8 DER (96 hex chars) |
+| `NOORM_IDENTITY_NAME` | Display name |
+| `NOORM_IDENTITY_EMAIL` | Email address |
+
+The public key is *derived* from the private key rather than supplied. The
+identityHash is then computed with `machine: publicKey` and `os: 'env'` — the
+hostname is deliberately excluded, otherwise every CI runner would appear as a
+new user in the audit trail. Any missing var, a key that fails hex/length
+validation, or a key that will not parse as X25519 returns `null` rather than
+throwing.
+
+Installation happens once at process startup — `entry()` in `src/cli/index.ts`
+for the CLI, and `createContext()` in `src/sdk/index.ts` for SDK consumers:
+
+```typescript
+import { loadIdentityFromEnv } from './core/identity/env'
+import { setKeyOverride, setIdentityOverride } from './core/identity/storage'
+
+const envIdentity = loadIdentityFromEnv()
+
+if (envIdentity) {
+    setKeyOverride(envIdentity.privateKey)
+    setIdentityOverride(envIdentity.identity)
+}
+```
+
+The overrides are process-wide module state. Once set, `loadPrivateKey()` and
+`loadIdentityMetadata()` return the env values for the lifetime of the process
+and never read `~/.noorm/`. `setKeyOverride` re-validates its argument — it is a
+public export, so the env loader's own check is not sufficient; malformed key
+material flows straight into `deriveStateKey` and would silently derive a
+publicly computable encryption key.
+
+`clearKeyOverride()` / `clearIdentityOverride()` undo it (used by tests).
 
 
 ## Additional Utilities
@@ -285,6 +343,8 @@ The identity module exports several utility functions:
 import {
     loadExistingIdentity,            // Load identity from global ~/.noorm/
     syncIdentityWithConfig,          // Sync identity with database on config activation
+    registerIdentity,                // Upsert one identity row (used by withVaultContext)
+    fetchKnownUsers,                 // Read all identity rows as KnownUser[]
     clearIdentityCache,              // Clear cached audit identity
     getIdentityForConfig,            // Extract identity override from config
     getIdentityWithCrypto,           // Resolve with crypto identity awareness
@@ -304,15 +364,34 @@ import {
     getPublicKeyPath,                // Get path to public key file
     getNoormHomePath,                // Get path to noorm home directory
     truncateHash,                    // Truncate identity hash for display
+    loadIdentityFromEnv,             // Reconstruct a CryptoIdentity from NOORM_IDENTITY_*
+    setKeyOverride,                  // Install the process-wide private key override
+    setIdentityOverride,             // Install the process-wide metadata override
 } from './core/identity'
 ```
 
+`detectIdentityDefaults` and `regenerateKeyPair` are worth a note: the first is
+synchronous despite reading git config (it shells out with `execSync`), and the
+second takes the existing `CryptoIdentity` and returns a new one with the same
+identityHash — the hash derives from user details, not from the keys.
+
+Anything that replaces the keypair makes every existing `state.enc` on the
+machine undecryptable, and nothing re-encrypts state under a new key. That is why
+`backupKeyPair()` throws rather than continuing if the private key exists but
+cannot be copied aside. It is the one storage helper the module index does not
+re-export — import it from `./core/identity/storage` directly, as
+`src/cli/identity/init.ts` does.
+
 
 ## CLI Workflow
 
-The TUI provides screens for managing identity:
+Headless identity management lives under `noorm identity`, a citty parent with
+four leaves — `init`, `edit`, `export`, `list`. It has no `run` handler, so bare
+`noorm identity` renders help rather than opening a screen.
+
+The TUI provides equivalent screens, reached via `noorm ui`:
 
-**Identity Screen** (`noorm identity` or `[i]` from home)
+**Identity Screen** (`[i]` from the TUI home screen)
 
 Displays current identity details: name, email, machine, OS, truncated hash/public key, and creation date. Also shows count of known users discovered from database sync.
 
diff --git a/docs/dev/index.md b/docs/dev/index.md
index 983a1cd1..b1539222 100644
--- a/docs/dev/index.md
+++ b/docs/dev/index.md
@@ -22,9 +22,11 @@ For user-facing documentation, see the [main docs](/).
 - [SQL Terminal](./sql-terminal.md) - Interactive REPL
 - [Templates](./template.md) - Eta templating engine
 - [Secrets](./secrets.md) - Encrypted secret storage
+- [Vault](./vault.md) - Team-shared encrypted secrets
 - [Locking](./lock.md) - Concurrency control
 - [Teardown](./teardown.md) - Database reset operations
 - [Data Transfer](./transfer.md) - Cross-database data transfer
+- [Config Sharing](./config-sharing.md) - Exporting and importing configs
 
 
 ## Integration
diff --git a/docs/dev/ink-cheatsheet.md b/docs/dev/ink-cheatsheet.md
index 20e3b4a0..b2a3529b 100644
--- a/docs/dev/ink-cheatsheet.md
+++ b/docs/dev/ink-cheatsheet.md
@@ -1,7 +1,9 @@
 # Ink Cheatsheet
 
 
-A comprehensive reference for building CLI applications with Ink (React for the terminal).
+A reference for building CLI applications with Ink (React for the terminal).
+
+This page documents the upstream Ink API, not noorm's own TUI. Where the two diverge, noorm's rules win—see `.claude/rules/tui-development.md`. The divergences are called out inline below. Installed here: `ink@^6.8.0`, `react@^19.2.4`, `@inkjs/ui@^2.0.0`.
 
 
 ## Table of Contents
@@ -20,17 +22,21 @@ A comprehensive reference for building CLI applications with Ink (React for the
 ## Installation
 
 
+Already installed in this repo—`bun install` is enough. For a new project:
+
 ```bash
-npm install ink react
-npm install --save-dev @types/react @types/node typescript
+bun add ink react
+bun add -d @types/react @types/node typescript
 ```
 
 For Ink UI components:
 
 ```bash
-npm install @inkjs/ui
+bun add @inkjs/ui
 ```
 
+This repo is Bun-managed (`bun.lockb`, `bunfig.toml`, `engines.bun >= 1.2`). Running `npm install` here creates a conflicting lockfile.
+
 
 ## Core Concepts
 
@@ -119,6 +125,8 @@ import { Box, Text } from "ink";
 
 #### Box Props Reference
 
+Layout props only. `borderStyle`, `borderColor`, the individual `borderTop`/`borderBottom`/`borderLeft`/`borderRight` booleans, and `backgroundColor` are covered in the two sections that follow.
+
 | Prop | Type | Description |
 |------|------|-------------|
 | `flexDirection` | `row` \| `column` \| `row-reverse` \| `column-reverse` | Direction of flex items |
@@ -424,6 +432,10 @@ useInput(
 
 ### useFocus
 
+::: danger Not used in noorm
+`useFocus` and `useFocusManager` drive Ink's *internal* focus registry, which does not communicate with noorm's. Mixing the two loses keyboard input. In `src/tui/`, use `useFocusScope` from `src/tui/focus.tsx`, inside a `FocusProvider`. The rest of this section is upstream reference only.
+:::
+
 Make components focusable (Tab/Shift+Tab navigation).
 
 ```tsx
@@ -579,7 +591,7 @@ function App() {
 ## Ink UI Components
 
 
-Install: `npm install @inkjs/ui`
+Install: `bun add @inkjs/ui` (already a dependency here)
 
 ```tsx
 import {
@@ -595,10 +607,13 @@ import {
     Alert,
     UnorderedList,
     OrderedList,
-    ThemeProvider,
 } from "@inkjs/ui";
 ```
 
+::: warning Only four are usable in noorm
+`TextInput` (with `isDisabled`), `Spinner`, `Badge`, and `ProgressBar` are display-only or properly controlled, so they compose with noorm's focus system. `Select`, `MultiSelect`, and `ConfirmInput` drive Ink's internal focus and are **incompatible**—build the equivalent from `useFocusScope` + `useInput` instead. Their sections below are upstream reference only.
+:::
+
 
 ### TextInput
 
@@ -757,7 +772,11 @@ import {
 ## Meow (Argument Parsing)
 
 
-Meow is the recommended argument parser for Ink CLI apps. It handles `--help`, `--version`, flags, and positional arguments.
+::: warning noorm does not use Meow
+noorm parses arguments with **citty** (`src/cli/`), and `meow` is not a dependency. This section is kept as general Ink-ecosystem reference; do not add Meow to this repo. For how noorm's commands are defined, see [CLI](/dev/headless).
+:::
+
+Meow is a common argument parser for Ink CLI apps. It handles `--help`, `--version`, flags, and positional arguments.
 
 ```bash
 npm install meow
@@ -1377,7 +1396,7 @@ useInput(handler, { isActive: isFocused });
 Use `ink-testing-library`:
 
 ```bash
-npm install --save-dev ink-testing-library
+bun add -d ink-testing-library
 ```
 
 ```tsx
@@ -1395,7 +1414,7 @@ Colors may not display in CI environments. Check `process.stdout.isTTY`.
 
 ### Argument Parsing
 
-Use `meow` or `yargs` for CLI arguments:
+In noorm, use **citty** — see `src/cli/`. Outside this repo, `meow` and `yargs` are the common choices:
 
 ```bash
 npm install meow
diff --git a/docs/dev/ink-testing-library-cheatsheet.md b/docs/dev/ink-testing-library-cheatsheet.md
index 06972e38..1efd2cba 100644
--- a/docs/dev/ink-testing-library-cheatsheet.md
+++ b/docs/dev/ink-testing-library-cheatsheet.md
@@ -1,7 +1,12 @@
 # Ink Testing Library Cheatsheet
 
 
-A comprehensive reference for testing Ink CLI applications with ink-testing-library.
+A reference for testing Ink CLI applications with ink-testing-library (`^4.0.0` here).
+
+Two things differ in this repo, and they apply to every example below:
+
+- **The runner is `bun:test`, not Jest.** Import `describe`/`it`/`expect`/`vi` from `bun:test`. There is no `jest` or `@jest/globals` dependency.
+- **Describe blocks are named `'module: feature'`** per `.claude/rules/testing.md`—e.g. `describe('cli: focus', ...)`, not `describe('FocusItem', ...)`. The bare-component-name form used in the examples is illustrative only.
 
 
 ## Table of Contents
@@ -20,7 +25,7 @@ A comprehensive reference for testing Ink CLI applications with ink-testing-libr
 
 
 ```bash
-npm install --save-dev ink-testing-library
+bun add -d ink-testing-library
 ```
 
 
@@ -481,28 +486,22 @@ describe("AsyncLoader", () => {
 
 ### Testing with Fake Timers
 
-```tsx
-import { jest } from "@jest/globals";
-
-describe("AsyncLoader with fake timers", () => {
-
-    beforeEach(() => {
+::: warning Not the pattern used here
+No test in this repo uses fake timers, and `jest`/`@jest/globals` are not installed. Timing-dependent TUI tests wait on real timers instead (see the focus example below). Keep this section as generic reference; if you need it, reach for `bun:test`'s own timer mocking, not Jest's.
+:::
 
-        jest.useFakeTimers();
-    });
+```tsx
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
 
-    afterEach(() => {
+describe("cli: async loader", () => {
 
-        jest.useRealTimers();
-    });
-
-    it("should transition states", () => {
+    it("should transition states", async () => {
 
         const { lastFrame } = render(<AsyncLoader />);
 
         expect(lastFrame()).toBe("Loading...");
 
-        jest.advanceTimersByTime(150);
+        await new Promise((r) => setTimeout(r, 150));
 
         expect(lastFrame()).toBe("Loaded!");
     });
@@ -534,7 +533,7 @@ describe("DataFetcher", () => {
 
     it("should display fetched data", async () => {
 
-        const mockFetch = jest.fn().mockResolvedValue("Fetched data");
+        const mockFetch = vi.fn().mockResolvedValue("Fetched data");
         const { lastFrame } = render(<DataFetcher fetchFn={mockFetch} />);
 
         expect(lastFrame()).toBe("Loading...");
@@ -546,7 +545,7 @@ describe("DataFetcher", () => {
 
     it("should display error on failure", async () => {
 
-        const mockFetch = jest.fn().mockRejectedValue(new Error("Network error"));
+        const mockFetch = vi.fn().mockRejectedValue(new Error("Network error"));
         const { lastFrame } = render(<DataFetcher fetchFn={mockFetch} />);
 
         await new Promise(process.nextTick);
@@ -606,7 +605,7 @@ function TestWrapper({ onInput }: { onInput: (input: string) => void }) {
 
 it("should capture input", () => {
 
-    const onInput = jest.fn();
+    const onInput = vi.fn();
     const { stdin } = render(<TestWrapper onInput={onInput} />);
 
     stdin.write("x");
@@ -654,45 +653,72 @@ describe("ExitOnQ", () => {
 
 ### Testing Focus
 
+noorm does not use Ink's `useFocus`. Components take focus through `useFocusScope` inside a `FocusProvider` (`src/tui/focus.tsx`).
+
+Two things follow from how that provider works, and both shape the test:
+
+- Focus is a **stack**, not a Tab ring. `useFocusScope` pushes on mount and pops on unmount; whichever scope is on top is focused. Tab does not cycle between siblings—mounting and unmounting is what moves focus.
+- The push happens in `useEffect`, so `isFocused` is false on the first frame. Wait before asserting, and again after any `stdin.write`.
+
 ```tsx
-import { useFocus, Text } from "ink";
+import { describe, it, expect } from "bun:test";
+import { render } from "ink-testing-library";
+import { Box, Text } from "ink";
+
+import { FocusProvider, useFocusScope } from "../../src/tui/focus.js";
 
-function FocusableItem({ id }: { id: string }) {
+function Panel({ label }: { label: string }) {
 
-    const { isFocused } = useFocus({ id });
+    const { isFocused } = useFocusScope(label);
 
     return (
         <Text color={isFocused ? "green" : "white"}>
-            {isFocused ? "> " : "  "}Item {id}
+            {isFocused ? "> " : "  "}{label}
         </Text>
     );
 }
 
-describe("FocusableItem", () => {
+describe("cli: panel focus", () => {
 
-    it("should show focus indicator when focused", () => {
+    it("should hand focus back when the top scope unmounts", async () => {
 
-        const { lastFrame, stdin } = render(
-            <Box flexDirection="column">
-                <FocusableItem id="1" />
-                <FocusableItem id="2" />
-            </Box>
+        const { lastFrame, rerender, unmount } = render(
+            <FocusProvider>
+                <Box flexDirection="column">
+                    <Panel label="list" />
+                    <Panel label="detail" />
+                </Box>
+            </FocusProvider>
         );
 
-        // First item focused by default (if autoFocus)
-        expect(lastFrame()).toContain("> Item 1");
+        // Focus stack initializes in useEffect — wait before asserting
+        await new Promise((r) => setTimeout(r, 50));
+        expect(lastFrame()).toContain("> detail");   // last pushed wins
 
-        // Tab to next item
-        stdin.write("\t");
-        expect(lastFrame()).toContain("> Item 2");
+        rerender(
+            <FocusProvider>
+                <Box flexDirection="column">
+                    <Panel label="list" />
+                </Box>
+            </FocusProvider>
+        );
+
+        await new Promise((r) => setTimeout(r, 50));
+        expect(lastFrame()).toContain("> list");
+
+        unmount();  // Clean up stdin handlers
     });
 });
 ```
 
+Real examples live in `tests/cli/focus.test.tsx`, which also sets `IS_REACT_ACT_ENVIRONMENT = true`—React 19 needs it for `act()` to flush effects outside a browser.
+
+When a test does send keys, the codes are `\x1b[B` (down), `\x1b[A` (up), `\r` (enter), `\x1b` (escape), with a wait on either side of the write.
+
 
 ### Cleanup Between Tests
 
-Always unmount or let jest handle cleanup:
+Always unmount when the test is done:
 
 ```tsx
 describe("MyComponent", () => {
diff --git a/docs/dev/lock.md b/docs/dev/lock.md
index b8421c31..2794e2c3 100644
--- a/docs/dev/lock.md
+++ b/docs/dev/lock.md
@@ -14,17 +14,22 @@ noorm solves this with table-based locking. Before any operation touches the dat
 
 ## How It Works
 
-All locking happens through a single table: `__noorm_lock__`. Each config gets its own lock scope - two developers can work on different configs simultaneously, but not the same one.
+All locking happens through a single table: `__noorm_lock__` on MySQL and SQLite, or `noorm.lock` in the dedicated schema on PostgreSQL and SQL Server. Each config gets its own lock scope - two developers can work on different configs simultaneously, but not the same one.
 
 ```
 __noorm_lock__
-├── config_name   # Which config/database this lock protects
+├── id            # Auto-increment primary key
+├── config_name   # Which config/database this lock protects — UNIQUE
 ├── locked_by     # Identity of the holder
 ├── locked_at     # When acquired
 ├── expires_at    # Auto-expiry time
-└── reason        # Optional explanation
+└── reason        # Explanation, NOT NULL, defaults to ''
 ```
 
+The `UNIQUE` constraint on `config_name` is what makes acquisition safe: `acquire` claims the lock with a single `INSERT ... ON CONFLICT DO NOTHING` (`INSERT IGNORE` on MySQL, a plain insert arbitrated by the constraint on MSSQL, which has no `ON CONFLICT`). A `SELECT`-then-`INSERT` would leave a window where two processes both see "no lock" and both insert. Losing the race returns `null` internally and becomes a typed `LockAcquireError`, not a raw driver error.
+
+`locked_at` and `expires_at` are naive datetime columns — no stored offset. `manager.ts` serializes UTC and parses back as UTC per dialect (`formatDateForDialect` / `parseDateFromDialect`, `src/core/lock/manager.ts:68` and `:96`). Passing a JS `Date` straight through is the defect those functions exist to prevent: the postgres and mysql drivers bind using the *client's* local offset, so a `lock status` run from another timezone would compare two unrelated wall clocks and delete a live lock.
+
 Locks expire automatically. If a process crashes mid-operation, the next acquire attempt cleans up the stale lock after expiry. No manual intervention needed.
 
 
@@ -76,7 +81,9 @@ try {
 }
 finally {
 
-    await lockManager.release(db, 'production', 'alice@example.com')
+    // `release` takes the dialect explicitly — it has no default, because it
+    // resolves the schema-qualified vs prefixed table name from it.
+    await lockManager.release(db, 'production', 'alice@example.com', 'postgres')
 }
 ```
 
@@ -87,12 +94,15 @@ Configure lock behavior with these options:
 
 | Option | Default | Description |
 |--------|---------|-------------|
+| `dialect` | `'postgres'` | Resolves the lock table name and the datetime serialization |
 | `timeout` | 5 minutes | Lock duration before auto-expiry |
 | `wait` | `false` | Block until lock is available? |
 | `waitTimeout` | 30 seconds | Max time to wait (if `wait` is true) |
 | `pollInterval` | 1 second | Check frequency while waiting |
 | `reason` | none | Shown to blocked users |
 
+`dialect` defaults to `'postgres'` on every option-taking method (`acquire`, `withLock`, `extend`, `validate`, `status`). Against MySQL or SQLite you must pass it, or the manager looks for `noorm.lock` in a schema those dialects don't have.
+
 ```typescript
 // Fail immediately if locked
 await lockManager.acquire(db, configName, identity)
@@ -161,6 +171,7 @@ Note: Re-acquiring a lock you already hold also extends it (see "Re-acquiring Yo
 Before committing critical changes, verify your lock is still valid:
 
 ```typescript
+import { attempt } from '@logosdx/utils'
 import { LockExpiredError } from './core/lock'
 
 // Start a transaction
@@ -169,38 +180,41 @@ await db.transaction().execute(async (trx) => {
     await processChanges(trx)
 
     // Before committing, verify lock hasn't expired
-    try {
+    const [, err] = await attempt(() =>
+        lockManager.validate(db, configName, identity, 'postgres')
+    )
 
-        await lockManager.validate(db, configName, identity)
-        // Lock is valid, safe to commit
+    if (err instanceof LockExpiredError) {
+
+        // Lock expired! Roll back
+        throw new Error('Lock expired during operation')
     }
-    catch (err) {
 
-        if (err instanceof LockExpiredError) {
+    if (err) throw err
 
-            // Lock expired! Roll back
-            throw new Error('Lock expired during operation')
-        }
-        throw err
-    }
+    // Lock is valid, safe to commit
 })
 ```
 
+`validate` also throws `LockNotFoundError` when no row exists and `LockOwnershipError` when someone else holds it. On expiry it cleans the stale row up before throwing.
+
 
 ## Force Release
 
 Admins can force-release locks regardless of owner. Use sparingly:
 
 ```typescript
-// Returns true if a lock was released, false if none existed
-const released = await lockManager.forceRelease(db, 'production')
+// Returns { released, holder } — `holder` is null when there was nothing to release
+const { released, holder } = await lockManager.forceRelease(db, 'production', 'postgres')
 
 if (released) {
 
-    console.log('Forced lock release')
+    console.log(`Forced release of lock held by ${holder}`)
 }
 ```
 
+`forceRelease` returns a `ForceReleaseResult`, not a boolean, and it carries the evicted holder. Breaking someone else's lock is destructive to their in-flight work, so callers need to be able to say *whose* lock they broke — and to tell "evicted a live holder" apart from "there was nothing there", which a bare boolean collapsed into the same success.
+
 This is intended for CLI commands like `noorm lock force-release` when a crashed process left a lock behind.
 
 **Note**: `forceRelease` emits a `lock:released` event when successful.
diff --git a/docs/dev/logger.md b/docs/dev/logger.md
index 173eb99d..deac4ced 100644
--- a/docs/dev/logger.md
+++ b/docs/dev/logger.md
@@ -25,14 +25,16 @@ noorm solves this with persistent file logging. Every significant event is captu
 ┌─────────────────────────────────────────────────────────────┐
 │                         Logger                               │
 │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
-│  │Classifier│→ │Formatter │→ │  Queue   │→ │   File   │    │
+│  │  Queue   │→ │Classifier│→ │Formatter │→ │   File   │    │
 │  │          │  │          │  │          │  │          │    │
-│  │ Determine│  │ Create   │  │ Non-     │  │ Append   │    │
-│  │ level    │  │ entry    │  │ blocking │  │ + rotate │    │
+│  │ Non-     │  │ Determine│  │ Redact + │  │ Append   │    │
+│  │ blocking │  │ level    │  │ flatten  │  │ + rotate │    │
 │  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+The queue is at the front, not the back: it decouples the *emitter* from the logger. Once an event is dequeued, classification, formatting, and the file write all happen synchronously.
+
 
 ## Quick Start
 
@@ -45,7 +47,7 @@ await settings.load()
 
 const logger = new Logger({
     projectRoot: process.cwd(),
-    settings,  // Required for secret detection/redaction
+    settings,  // Required field, but the class does not read it
     config: settings.getLogging(),
 })
 
@@ -108,12 +110,27 @@ shouldLog('file:before', 'verbose')    // true (verbose logs all)
 
 Events are automatically classified by their naming pattern:
 
-| Pattern | Level | Examples |
-|---------|-------|----------|
-| `error`, `*:error`, `*:failed` | error | `error`, `connection:error`, `build:failed` |
-| `*:warning`, `*:blocked`, `*:expired` | warn | `lock:blocked`, `lock:expired` |
-| `*:start`, `*:complete`, `*:created`, `*:deleted`, `*:loaded`, etc. | info | `build:start`, `config:created` |
-| Everything else | debug | `file:before`, `lock:acquiring` |
+Rules are checked in this order; the first match wins.
+
+| # | Pattern | Level | Examples |
+|---|---------|-------|----------|
+| 1 | `error`, `*:error`, `*:failed` | error | `error`, `connection:error`, `build:failed` |
+| 2 | `*:warning`, `*:blocked`, `*:expired` | warn | `lock:blocked`, `lock:expired` |
+| 3 | `*:before`, `*:acquiring`, `*:file` | debug | `file:before`, `lock:acquiring` |
+| 4 | Known namespace prefix (below) | info | `build:start`, `config:created` |
+| 5 | Everything else | debug | `mcp:tool-called` |
+
+Rule 4 matches on the event's **namespace prefix**, not its suffix. Any event in one of these namespaces is info unless rule 1, 2, or 3 already claimed it:
+
+```
+update:  global-settings:  settings:  file:  change:  build:  run:  lock:
+state:   config:  secret:  known-user:  db:  template:  identity:
+connection:  app:  transfer:  dt:  vault:
+```
+
+Rule 3 exists because `file:` and `lock:` are info namespaces, but `file:before` and `lock:acquiring` fire on every file and every acquisition attempt—too noisy for default verbosity. It is checked before rule 4 so the namespace can't win.
+
+An event in a namespace *not* on that list falls to debug regardless of its suffix: a hypothetical `plugin:start` is debug, not info.
 
 ```typescript
 import { classifyEvent } from './core/logger'
@@ -131,19 +148,21 @@ classifyEvent('file:before')      // 'debug'
 Each entry is a JSON object on a single line:
 
 ```json
-{"time":"2024-01-15T10:30:00.000Z","type":"build:start","level":"info","message":"Starting schema build (10 files)","context":{"config":"dev"}}
+{"time":"2024-01-15T10:30:00.123+00:00","type":"build:start","level":"info","message":"Starting schema build (10 files)","fileCount":10,"config":"dev"}
 ```
 
-Entry structure:
+Four core fields are always present:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `time` | string | ISO 8601 timestamp |
+| `time` | string | Local time with a `±HH:mm` UTC offset—never a literal `Z` |
+| `type` | string | Observer event name, or `log` for a direct `logger.info()`-style call |
 | `level` | string | `error`, `warn`, `info`, or `debug` |
-| `type` | string | Observer event name |
 | `message` | string | Human-readable summary |
-| `data` | object | Event payload (verbose only) |
-| `context` | object | Config name, identity, etc. |
+
+Everything else—the event payload, then the injected context—is **flattened onto the same object**, not nested under `data` or `context`. Nested values are flattened one level with dot-notation (`connection.host`), arrays and anything deeper are JSON-stringified, and a key that collides with an existing one is dropped rather than overwriting it. Payload fields are written whenever the payload is non-empty; there is no verbose-only gate.
+
+A `formatEntry()` helper in `formatter.ts` does build a nested `{ data, context }` shape, but nothing on the write path calls it—do not use it as a reference for what lands on disk.
 
 The `message` field provides human-readable summaries:
 
@@ -204,7 +223,7 @@ maskValue('mysecretpassword', 'Password', 'info')
 
 // In verbose mode, first few chars are visible for debugging
 maskValue('sk-1234567890abcd', 'ApiKey', 'verbose')
-// => '<ApiKey sk-1********... (18) />'
+// => '<ApiKey sk-1********... (17) />'
 ```
 
 The mask length is capped at 12 characters, with `...` indicating overflow. In verbose mode, up to 4 leading characters are revealed (proportional to value length) to help identify which secret is being referenced.
@@ -218,11 +237,14 @@ Common sensitive field names are automatically detected (case-insensitive):
 password, pass, secret, token, key, credential, api_key, apikey,
 access_key, secret_key, db_pass, db_password, redis_pass,
 client_secret, private_key, encryption_key, auth_token,
-bearer_token, jwt_secret, session_secret
+bearer_token, jwt_secret, session_secret,
+connection_password, identity_private_key, password_hash, user_password
 ```
 
 All case variations are checked: `password`, `PASSWORD`, `Password`, `db_password`, `DB_PASSWORD`, `dbPassword`, etc.
 
+The last four are listed in full for a reason: `addMaskedFields` derives the `NOORM_` prefix from the **bare** term only, so `password` yields `NOORM_PASSWORD` but never `NOORM_CONNECTION_PASSWORD`. Any compound env var name this project actually tells users to set has to be registered explicitly.
+
 
 ### Dynamic Secret Registration
 
@@ -242,30 +264,32 @@ const cleanup = listenForSecrets()
 // Now any secret:set or global-secret:set events add keys to redaction
 ```
 
-The logger calls `listenForSecrets()` at startup, so any secret you set during a session is immediately masked in logs.
+**The `Logger` class does not call these for you.** Only `enableAutoLoggerInit()` (the TUI path) wires `addSettingsSecrets` and `listenForSecrets`. The headless CLI's `createCliLogger()` calls neither, so in a headless run only the built-in field-name list applies—a secret set mid-session is not auto-redacted unless you wire it yourself, as the example above does.
 
 
-## Write Queue
+## Event Queue
 
-The logger uses a non-blocking queue for file writes:
+Incoming observer events are processed through `observer.queue()`, an `EventQueue` with concurrency 1:
 
-- **Non-blocking enqueue** - Callers never wait for disk I/O
-- **Order preservation** - Entries written in enqueue order
-- **Graceful shutdown** - Flush waits for pending writes
+- **Non-blocking** - Emitters never wait for the logger
+- **Order preservation** - Events processed in emit order
+- **Graceful shutdown** - `stop()` drains the queue before closing the stream
 
 ```typescript
-// Entries enqueued immediately (non-blocking)
+// Emitters return immediately
 observer.emit('config:created', { name: 'dev' })
 observer.emit('config:created', { name: 'prod' })
 
-// Flush forces all pending writes to complete
+// Flush forces pending work to complete
 await logger.flush()
 
 // Stop flushes before shutting down
 await logger.stop()
 ```
 
-The `WriteQueue` class also exposes a `setFilepath()` method, used internally during log rotation to switch the queue to writing to a new file path.
+The queue sits in front of event *processing*. The file write itself is a plain synchronous `Writable#write()`, and rotation reopens the stream rather than redirecting a queue.
+
+`src/core/logger/queue.ts` exports a `WriteQueue` class with its own `setFilepath()`. It is **not wired into `Logger`**—nothing outside its own unit test constructs it. Do not read it as the active write path.
 
 
 ## Log Rotation
@@ -291,6 +315,10 @@ const result = await checkAndRotate('/path/to/app.log', '10mb', 5)
 // { rotated: true, oldFile: '...', newFile: '...', deletedFiles: [...] }
 ```
 
+A running logger does this on its own: `start()` checks once before opening the stream, then installs a 60-second interval that calls `logger.checkRotation()` until `stop()`. Calling `checkAndRotate` yourself is only for tooling outside a live logger.
+
+In the `logger:rotated` payload, `oldFile` is the live path (`noorm.log`) and `newFile` is the timestamped archive it was moved to—a fresh file then reappears at `oldFile`.
+
 
 ## Context Injection
 
@@ -313,42 +341,85 @@ logger.setContext({ config: 'prod', user: 'alice' })
 logger.clearContext()
 ```
 
-Context appears in every entry:
+Context is flattened onto every entry alongside the payload, not nested:
 
 ```json
-{"time":"...","type":"build:start","level":"info","message":"...","context":{"config":"prod","user":"alice"}}
+{"time":"...","type":"build:start","level":"info","message":"...","fileCount":10,"config":"prod","user":"alice"}
 ```
 
+Context is applied after the payload, so a payload field of the same name wins.
+
 
 ## Logger API
 
 ```typescript
 const logger = new Logger({
     projectRoot: string,
-    settings: Settings,           // Required for secret detection
+    settings: Settings,           // Required field; the class does not read it
     config?: Partial<LoggerConfig>,
     context?: Record<string, unknown>,
     file?: Writable,              // Custom file stream
-    console?: Writable,           // Custom console stream (defaults to stdout in CI)
+    console?: Writable,           // Result output only (default process.stdout)
+    diagnostics?: Writable,       // Every log line goes here (default process.stderr)
+    json?: boolean,               // NDJSON console output (default: isCi())
+    color?: boolean,              // Colored inline console output
 })
 
 // Lifecycle
-await logger.start()   // Subscribe to events, start queue
-await logger.stop()    // Unsubscribe, flush, stop queue
+await logger.start()   // Subscribe to events, start queue, arm rotation interval
+await logger.stop()    // Unsubscribe, flush, close stream
 await logger.flush()   // Force pending writes to disk
 
+// Direct logging (bypasses the observer; entries get type "log")
+logger.info(message, data?)
+logger.warn(message, data?)
+logger.error(message, data?)
+logger.debug(message, data?)
+
+// Headless command result — raw JSON to console AND the log file
+logger.result(data)
+
 // State
 logger.state           // 'idle' | 'running' | 'flushing' | 'stopped'
 logger.level           // Current log level
 logger.filepath        // Full path to log file
 logger.isEnabled       // Whether logging is active
 logger.stats           // Queue statistics (pending, totalWritten, etc.)
+logger.checkRotation() // Manual rotation check; also runs on a 60s interval
 
 // Context
 logger.setContext({ key: value })  // Merge into context
 logger.clearContext()              // Clear all context
 ```
 
+`console` and `diagnostics` are not interchangeable. Every log line—observer-driven or direct—goes to `diagnostics` (stderr). `console` (stdout) carries only `result()`'s payload, which is what keeps `--json` output parseable: the event stream never contaminates stdout.
+
+The constructor also subscribes to `app:shutdown` and calls `stop()` on it, so a clean shutdown flushes without an explicit call.
+
+
+## Constructing a Logger
+
+Two factories cover the real paths; construct `Logger` directly only in tests.
+
+| Factory | Used by | Behavior |
+|---------|---------|----------|
+| `createCliLogger(projectRoot, json)` | Every headless CLI command | Loads settings, defaults level to `verbose` under `isDev()` else `info`, honors `NOORM_LOG_LEVEL`, sets `console: stdout` / `diagnostics: stderr`, `color: !json` |
+| `enableAutoLoggerInit()` | The TUI (`noorm ui`) | Event-driven bootstrap; also wires `addSettingsSecrets` + `listenForSecrets`, and forces the log file path empty under `isCi()` |
+
+`logging.enabled: false` in settings does not disable the whole logger in the CLI path—it blanks the file path, leaving console output intact. A blank `config.file` is how the logger is told to stay console-only.
+
+
+### Environment variables
+
+| Variable | Effect |
+|----------|--------|
+| `NOORM_LOG_LEVEL` | Overrides `logging.level`. Read only in the `createCliLogger` path |
+| `NOORM_LOGGER_DEBUG` | Enables debug tracing on the internal event queue |
+| `NOORM_DEV` / `NODE_ENV=development` | Via `isDev()`, raises the CLI's default level to `verbose` |
+| CI vars | Via `isCi()`, default `json` to true; the TUI init path additionally disables file logging |
+
+There is no `--verbose`, `--quiet`, or `--log-level` CLI flag. The only command-line lever is `--json`.
+
 
 ## Singleton Pattern
 
@@ -357,17 +428,21 @@ For convenience, use the singleton:
 ```typescript
 import { getLogger, resetLogger } from './core/logger'
 
-// First call initializes the singleton
+// First call initializes the singleton. A bare projectRoot string also works.
 const logger = getLogger({
     projectRoot: process.cwd(),
     settings,
     config: loggingConfig,
 })
-await logger.start()
+await logger?.start()
 
 // Subsequent calls return the existing instance (options ignored)
 const sameLogger = getLogger()
 
+// getLogger() returns Logger | null — null when called with no options
+// before anything has initialized the singleton
+sameLogger?.info('ready')
+
 // In tests, reset between tests
 await resetLogger()
 ```
@@ -381,10 +456,10 @@ The logger emits events for its own lifecycle:
 |-------|---------|------|
 | `logger:started` | `{ file, level }` | Logger initialized |
 | `logger:rotated` | `{ oldFile, newFile }` | Log file rotated |
-| `logger:error` | `{ error }` | Write failure |
-| `logger:flushed` | `{ entriesWritten }` | Queue drained |
 
-Note: The logger ignores its own events to avoid infinite loops.
+Those two are the whole set. `formatter.ts` carries message templates for `logger:error` and `logger:flushed`, but neither is declared in `NoormEvents` and neither is ever emitted—do not subscribe to them. File-stream errors are swallowed silently rather than reported.
+
+The logger ignores events whose name starts with `logger:` to avoid infinite loops.
 
 
 ## Integration Example
@@ -458,7 +533,7 @@ console.log(`Returned: ${result.entries.length}`)
 console.log(`Has more: ${result.hasMore}`)
 
 for (const entry of result.entries) {
-    console.log(`[${entry.level}] ${entry.event}: ${entry.message}`)
+    console.log(`[${entry.level}] ${entry.type}: ${entry.message}`)
 }
 
 // Read last 100 entries
@@ -496,7 +571,7 @@ The CLI includes a global log viewer accessible via `Shift+L` from anywhere in t
 │  10:30:46 [debug] file:before         Processing posts.sql  │
 │  10:30:47 [error] file:after          Failed: posts.sql     │
 │                                                              │
-│  ↑/↓ Navigate  Enter Detail  / Search  p Pause  Esc Close  │
+│  ↑/↓ Navigate  Enter Detail  / Search  Space Pause  Esc    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -515,7 +590,10 @@ Keyboard shortcuts:
 | Key | Action |
 |-----|--------|
 | `↑/↓` | Navigate entries |
+| `PageUp` / `PageDown` | Page through entries |
+| `g` / `G` | Jump to top / bottom |
 | `Enter` | View entry detail |
 | `/` | Toggle search filter |
-| `p` | Pause/resume live tail |
+| `Space` | Pause/resume live tail |
+| `r` | Refresh now |
 | `Esc` | Close overlay |
diff --git a/docs/dev/project-discovery.md b/docs/dev/project-discovery.md
index 5db32448..fd3cd52c 100644
--- a/docs/dev/project-discovery.md
+++ b/docs/dev/project-discovery.md
@@ -49,6 +49,8 @@ import {
     isNoormProject,
     getGlobalNoormPath,
     hasGlobalNoorm,
+    getOriginalCwd,
+    setOriginalCwd,
 } from './core/project.js'
 
 // Find project root without side effects
@@ -58,6 +60,9 @@ const result = findProjectRoot()
 // result.homeNoorm: '/Users/me/.noorm' or null
 // result.originalCwd: where the user actually ran the command
 
+// Start the walk somewhere other than process.cwd()
+const fromDir = findProjectRoot('/Users/me/projects/myapp/packages/db')
+
 // Find and chdir to project root (default behavior)
 const result = initProjectContext()
 // Now process.cwd() === result.projectRoot
@@ -69,21 +74,38 @@ const result = initProjectContext({ chdir: false })
 isNoormProject('/path/to/dir')    // checks if dir has .noorm/
 getGlobalNoormPath()               // returns ~/.noorm path
 hasGlobalNoorm()                   // checks if ~/.noorm exists
+getOriginalCwd()                   // cwd captured before any chdir
+setOriginalCwd(dir)                // records it; first call wins
 ```
 
+`initProjectContext()` calls `setOriginalCwd()` for you. Commands that must
+operate on where the user actually stood — `init --here`, for example — read
+`getOriginalCwd()` rather than `process.cwd()`.
+
 
 ## CLI Integration
 
-The CLI calls `initProjectContext()` at the very start of `main()`:
+The CLI resolves the working directory first thing in `entry()`
+(`src/cli/index.ts`). A `--cwd` flag wins outright; otherwise discovery runs:
 
 ```typescript
-async function main(): Promise<void> {
-    // First thing: find project and chdir
-    const projectDiscovery = initProjectContext()
+async function entry(): Promise<void> {
+
+    const { cwd: explicitCwd, rest: cleanArgv } = extractGlobalCwd(process.argv.slice(2))
+
+    if (explicitCwd !== null) {
+
+        setOriginalCwd(process.cwd())
+        process.chdir(resolve(process.cwd(), explicitCwd))
+
+    }
+    else {
+
+        initProjectContext()
 
-    // Now process.cwd() is the project root
-    enableAutoLoggerInit(process.cwd())
+    }
 
+    // Now process.cwd() is the project root (or the explicit --cwd)
     // ... rest of CLI initialization
 }
 ```
diff --git a/docs/dev/runner.md b/docs/dev/runner.md
index a3d7ec3d..c40869a2 100644
--- a/docs/dev/runner.md
+++ b/docs/dev/runner.md
@@ -38,13 +38,14 @@ When you run a file:
 
 Files are re-executed only when necessary:
 
-| Condition | Action |
-|-----------|--------|
-| New file (no previous record) | Run |
-| Checksum changed | Run |
-| Previous execution failed | Run |
-| `--force` flag | Run |
-| Unchanged and successful | Skip |
+| Condition | `RunReason` | Action |
+|-----------|-------------|--------|
+| New file (no previous record) | `new` | Run |
+| Checksum changed | `changed` | Run |
+| Previous execution failed | `failed` | Run |
+| Parent operation marked stale by teardown | `stale` | Run |
+| `--force` flag | `force` | Run |
+| Unchanged and successful | — | Skip (`skipReason: 'unchanged'`) |
 
 This makes builds idempotent—run the same build command twice and unchanged files won't re-execute.
 
@@ -57,8 +58,10 @@ This makes builds idempotent—run the same build command twice and unchanged fi
 | `abortOnError` | `true` | Stop on first failure |
 | `dryRun` | `false` | Render and write to `tmp/` without executing |
 | `preview` | `false` | Output rendered SQL to stdout/file |
+| `output` | `null` | File path for preview output |
+| `concurrency` | `1` | Reserved; see the note below |
 
-> **Note:** Files are always executed sequentially for DDL safety. Parallel execution is not currently supported.
+> **Note:** Files are always executed sequentially for DDL safety. `concurrency` exists on `RunOptions` and defaults to `1`, but parallel execution is not currently implemented.
 
 
 ## Dry Run Mode
@@ -122,7 +125,7 @@ The runner passes config, secrets, and project root to the template context. See
 
 ## Tracking Tables
 
-Every execution is recorded in two tables:
+Every execution is recorded in two tables. Names below are the MySQL/SQLite prefixed form; PostgreSQL and SQL Server use `noorm.change` and `noorm.executions` in a dedicated schema instead.
 
 **`__noorm_change__`** - Parent operation record:
 
@@ -132,7 +135,7 @@ Every execution is recorded in two tables:
 | `change_type` | `'build'` or `'run'` |
 | `executed_by` | Identity string |
 | `config_name` | Which config was used |
-| `status` | `'pending'`, `'success'`, `'failed'` |
+| `status` | `'pending'`, `'success'`, `'failed'` — teardown also rewrites forward rows to `'stale'` |
 
 **`__noorm_executions__`** - Individual file records:
 
@@ -268,15 +271,15 @@ An empty file (or one that contains only comments after stripping `GO`s) is trea
 
 | Event | Payload | Description |
 |-------|---------|-------------|
-| `build:start` | `{ schemaPath, fileCount }` | Build operation started |
-| `build:complete` | `{ status, filesRun, filesSkipped, filesFailed, durationMs }` | Build finished |
+| `build:start` | `{ sqlPath, fileCount }` | Build operation started |
+| `build:complete` | `{ status, filesRun, filesSkipped, filesFailed, durationMs, error? }` | Build finished |
 | `run:file` | `{ filepath, configName }` | Single file execution started |
 | `run:dir` | `{ dirpath, fileCount, configName }` | Directory execution started |
 | `run:files` | `{ fileCount, configName }` | Selective file execution started |
 | `file:before` | `{ filepath, checksum, configName }` | About to execute a file |
 | `file:after` | `{ filepath, status, durationMs, error? }` | File execution completed |
-| `file:skip` | `{ filepath, reason }` | File skipped (unchanged) |
-| `file:dry-run` | `{ filepath, outputPath }` | File written to tmp/ |
+| `file:skip` | `{ filepath, reason }` | File skipped; `reason` is `'unchanged'` or `'already-run'` |
+| `file:dry-run` | `{ filepath, status, outputPath?, error? }` | File rendered to `tmp/` (or failed to render) |
 
 ```typescript
 import { observer } from './core/observer'
@@ -347,35 +350,44 @@ This utility is used internally by build operations when applying settings rules
 
 ## Unified executeFiles
 
-The `executeFiles` function provides low-level file execution with full tracking. Both runner and change modules use this internally:
+The `executeFiles` function provides low-level file execution with full tracking. `runBuild`/`runDir`/`runFiles` funnel through it. The change module does **not** — `core/change/executor.ts` has its own private `executeFiles` so it can emit `change:file` events and honour manifest resolution; it shares only `computeChecksum`, `computeCombinedChecksum`, and the `Tracker` base class with the runner.
 
 ```typescript
-import { executeFiles, FileInput } from './core/runner'
+import { executeFiles, type FileInput } from './core/runner'
 
 // Prepare file inputs with pre-computed checksums
 const files: FileInput[] = [
-    { filepath: '/project/sql/001_users.sql', checksum: 'abc123' },
-    { filepath: '/project/sql/002_posts.sql', checksum: 'def456' },
+    { path: '/project/sql/001_users.sql', type: 'sql', checksum: 'abc123' },
+    { path: '/project/sql/002_posts.sql', type: 'sql', checksum: 'def456' },
 ]
 
-const result = await executeFiles(context, files, {
-    operationId,          // Pre-created operation ID
-    force: false,
-    abortOnError: true,
-    dryRun: false,
-})
+// Four arguments: run options and execution options are separate objects
+const result = await executeFiles(
+    context,
+    files,
+    { force: false, abortOnError: true, dryRun: false },   // RunOptions
+    {                                                       // ExecuteFilesOptions
+        changeType: 'build',
+        direction: 'commit',        // default: 'commit'
+        operationName: 'build:2024-01-15T10:30:00',
+        checksum: combinedChecksum, // optional
+        sqlPath: '/project/sql',    // optional, used in error messages
+    },
+)
 ```
 
 The `FileInput` type:
 
 ```typescript
 interface FileInput {
-    filepath: string
-    checksum: string      // Pre-computed SHA-256
-    fileType?: 'sql' | 'txt'  // Default: 'sql'
+    path: string
+    type: 'sql' | 'txt'
+    checksum?: string     // Pre-computed SHA-256; computed if omitted
 }
 ```
 
+`ExecuteFilesOptions` creates the operation record itself (or reuses a `tracker` you pass in) — there is no `operationId` parameter.
+
 This design separates file discovery (external) from execution (internal), enabling:
 - Pre-validation before database operations begin
 - Checksum computation for all files upfront
@@ -389,13 +401,21 @@ The `Tracker` class handles execution history and change detection. It serves as
 ```typescript
 import { Tracker } from './core/runner'
 
-const tracker = new Tracker(db)
+// (db, configName, dialect) — dialect defaults to 'sqlite', which selects the
+// prefixed table names. Pass the real dialect or pg/mssql queries hit the
+// wrong identifiers.
+const tracker = new Tracker(db, configName, 'postgres')
+
+// Check if file needs to run (by filepath). Returns NeedsRunResult:
+// { needsRun, reason?, skipReason?, previousChecksum? }
+const { needsRun, reason, skipReason } = await tracker.needsRun(filepath, checksum, force)
 
-// Check if file needs to run (by filepath)
-const { needsRun, reason, record } = await tracker.needsRun(filepath, checksum, force)
+// Inside a running operation, exclude that operation's own pending rows or
+// every file reads as 'new' forever
+const check = await tracker.needsRun(filepath, checksum, force, operationId)
 
 // Check if file needs to run (by name only - for changes)
-const { needsRun, reason, record } = await tracker.needsRunByName(name, checksum, force)
+const byName = await tracker.needsRunByName(name, checksum, force)
 
 // Create an operation record
 const operationId = await tracker.createOperation({
@@ -406,25 +426,23 @@ const operationId = await tracker.createOperation({
     executedBy: 'alice@example.com',
 })
 
-// Create file records upfront (for full batch visibility)
+// Create file records upfront (for full batch visibility) — fileType required
 await tracker.createFileRecords(operationId, [
-    { filepath: '/path/to/file1.sql', checksum: 'abc123' },
-    { filepath: '/path/to/file2.sql', checksum: 'def456' },
+    { filepath: '/path/to/file1.sql', fileType: 'sql', checksum: 'abc123' },
+    { filepath: '/path/to/file2.sql', fileType: 'sql', checksum: 'def456' },
 ])
 
-// Update individual file after execution
-await tracker.updateFileExecution(operationId, filepath, {
-    status: 'success',
-    durationMs: 45,
-    checksum: 'abc123',
-})
+// Update individual file after execution. Positional, not an options object:
+// (operationId, filepath, status, durationMs, errorMessage?, skipReason?, checksum?)
+await tracker.updateFileExecution(operationId, filepath, 'success', 45, undefined, undefined, 'abc123')
 
 // Skip remaining files (e.g., on error with abortOnError)
 await tracker.skipRemainingFiles(operationId, 'aborted due to previous error')
 
-// Legacy: Record a file execution (still supported)
+// Legacy: Record a file execution (still supported). Note the field is
+// `changeId`, not `operationId`.
 await tracker.recordExecution({
-    operationId,
+    changeId: operationId,
     filepath,
     checksum,
     status: 'success',
@@ -435,6 +453,8 @@ await tracker.recordExecution({
 await tracker.finalizeOperation(operationId, 'success', 1234, checksum, errorMessage)
 ```
 
+`createFileRecords`, `updateFileExecution`, `skipRemainingFiles`, and `finalizeOperation` return `string | null` — an error message on failure, `null` on success — rather than throwing. `createOperation` returns the new operation id.
+
 
 ### Direction and ChangeType
 
@@ -494,12 +514,19 @@ interface RunContext {
     configName: string
     identity: Identity
     projectRoot: string
+    access: ConfigAccess                    // the config's per-channel roles
+    channel: Channel                        // 'user' (CLI/TUI/SDK) or 'agent' (MCP)
+    dialect?: 'postgres' | 'mysql' | 'sqlite' | 'mssql'  // default: 'postgres'
     config?: Record<string, unknown>        // Config object for template context
     secrets?: Record<string, string>        // Config-scoped secrets
     globalSecrets?: Record<string, string>  // Global secrets from state
 }
 ```
 
+`access` and `channel` are required. Every exported entrypoint (`runBuild`, `runFile`, `runDir`, `runFiles`, `preview`, `checkFilesStatus`) runs `assertRunPolicy` against them once, at the core seam, so SDK/TUI/CLI/MCP callers inherit one enforcement path.
+
+`dialect` selects tracking-table naming (schema-qualified `noorm.*` on postgres/mssql, `__noorm_*__` elsewhere) and drives MSSQL batch splitting.
+
 The optional `config` field exposes the active configuration as a template variable, allowing templates to access config properties like database name, dialect, etc.
 
 
diff --git a/docs/dev/sdk.md b/docs/dev/sdk.md
index c667d559..f9fac514 100644
--- a/docs/dev/sdk.md
+++ b/docs/dev/sdk.md
@@ -55,20 +55,25 @@ The Context API is split into two levels:
 - `kysely`, `dialect`, `connected` — properties
 - `connect()`, `disconnect()` — lifecycle
 - `transaction()`, `proc()`, `func()`, `tvf()` — SQL execution
+- `impersonate()` — run queries as another database principal (callback or explicit scope)
 - `noorm` — namespace for management operations
 
 **ctx.noorm** — noorm management operations, organized by namespace:
 - `run`: `build()`, `file()`, `files()`, `dir()`, `discover()`, `preview()`
-- `db`: `truncate()`, `teardown()`, `previewTeardown()`, `reset()`, `listTables()`, `describeTable()`, `overview()`
-- `changes`: `apply()`, `revert()`, `ff()`, `status()`, `pending()`, `history()`, `create()`, `addFile()`, `removeFile()`, `renameFile()`, `reorderFiles()`, `delete()`, `discover()`, `parse()`, `validate()`
+- `db`: `truncate()`, `teardown()`, `previewTeardown()`, `reset()`, `overview()`, `listTables()`, `describeTable()`, `listViews()`, `describeView()`, `listProcedures()`, `describeProcedure()`, `listFunctions()`, `describeFunction()`, `listTypes()`, `describeType()`, `listIndexes()`, `listForeignKeys()`
+- `changes`: `apply()`, `revert()`, `ff()`, `next()`, `rewind()`, `status()`, `pending()`, `history()`, `historyForChange()`, `getFileHistory()`, `create()`, `addFile()`, `removeFile()`, `renameFile()`, `reorderFiles()`, `delete()`, `discover()`, `parse()`, `validate()`
 - `lock`: `acquire()`, `release()`, `status()`, `withLock()`, `forceRelease()`
 - `dt`: `exportTable()`, `importFile()`
 - `transfer`: `to()`, `plan()`
 - `templates`: `render()`
-- `secrets`: `get()`
+- `secrets`: `get()`, `list()`, `set()`, `delete()`
 - `vault`: `init()`, `status()`, `set()`, `get()`, `getAll()`, `list()`, `delete()`, `exists()`, `propagate()`, `copy()`
 - `utils`: `checksum()`, `testConnection()`
-- Properties: `config`, `settings`, `identity`, `observer`
+- Properties: `config`, `settings`, `identity`
+
+The event bus is **not** on the context. It is a process-global singleton exported
+as `noormObserver` from the package root — one `ObserverEngine` shared by every
+context in the process. See [Event Subscriptions](#event-subscriptions).
 
 
 ## API Reference
@@ -86,6 +91,7 @@ interface CreateContextOptions {
     projectRoot?: string     // Project root path (see note below)
     requireTest?: boolean    // Refuse if config.isTest !== true
     channel?: Channel        // 'user' (default) or 'agent' — which access role applies
+    yes?: boolean            // Pre-confirm 'confirm'-tier permissions (default: false)
     stage?: string           // Stage name for stage defaults
 }
 ```
@@ -107,7 +113,9 @@ const ctx = await createContext<MyDatabase>({
 
 - `requireTest: true` - Throws `RequireTestError` if the config doesn't have `isTest: true`. Use this in test suites to prevent accidentally running against production.
 
-- `channel: 'agent'` - Enforces the config's `access.agent` role instead of `access.user` for destructive operations (`truncate`, `teardown`, `reset`, `changes.revert`). Use this when embedding the SDK behind an MCP-like surface. Defaults to `'user'`. A denied or unconfirmable operation throws `ProtectedConfigError` — the SDK has no prompt, so a `confirm`-tier permission needs `NOORM_YES=1` or the CLI/TUI. See [Access Roles](./config.md#access-roles).
+- `channel: 'agent'` - Enforces the config's `access.agent` role instead of `access.user` for destructive operations (`truncate`, `teardown`, `reset`, `changes.revert`). Use this when embedding the SDK behind an MCP-like surface. Defaults to `'user'`. A denied or unconfirmable operation throws `ProtectedConfigError`. See [Access Roles](./config.md#access-roles).
+
+- `yes: true` - Pre-confirms `confirm`-tier permissions, the programmatic equivalent of the CLI's `--yes`. The SDK has no prompt, so without it a `confirm` cell blocks like an outright denial. Setting `NOORM_YES` in the environment has the same effect (`checkPolicy` consults it before returning `requiresConfirmation`). Both are **user-channel only**: on `agent`, `confirm` collapses to deny before either is read, so an agent cannot walk through a gate meant for a human.
 
 
 ### Environment Variable Support
@@ -326,7 +334,10 @@ for the consumer-side narrative.
 | `config`   | `Config`         | The resolved config object              |
 | `settings` | `Settings`       | Project settings (paths, rules, stages) |
 | `identity` | `Identity`       | Current operator identity               |
-| `observer` | `ObserverEngine` | Event observer for subscriptions        |
+
+All three are read-only getters over the shared `ContextState`. There is no
+`ctx.noorm.observer` — event subscription goes through the package-level
+`noormObserver` export.
 
 
 #### Schema Operations
@@ -636,10 +647,13 @@ await ctx.noorm.lock.withLock(async () => {
 
 ##### `lock.forceRelease()`
 
-Force release any database lock regardless of ownership. Returns `true` if a lock was released.
+Force release any database lock regardless of ownership. Returns a
+`ForceReleaseResult` — whether a lock was released, and who held it. Gated on the
+config's `lock:force` permission: `viewer` is denied outright, and
+`operator`/`admin` need `yes: true` (or `NOORM_YES`).
 
 ```typescript
-await ctx.noorm.lock.forceRelease()
+const { released, holder } = await ctx.noorm.lock.forceRelease()
 ```
 
 
@@ -763,7 +777,9 @@ const checksum = await ctx.noorm.utils.checksum('sql/001_users.sql')
 
 ##### `utils.testConnection()`
 
-Tests if the connection can be established without actually connecting.
+Opens a throwaway connection to the target database and immediately tears it
+down. Returns `{ ok, error? }` — failure as data, not an exception, which is a
+deliberate carve-out from the SDK's throwing convention.
 
 ```typescript
 const result = await ctx.noorm.utils.testConnection()
@@ -772,6 +788,12 @@ if (!result.ok) {
 }
 ```
 
+This probes the *target* database, so it fails when the database does not exist
+yet. Setup flows that only need to verify credentials call the core
+`testConnection(config, { testServerOnly: true })` from
+`src/core/connection/factory.ts` directly — the namespace method takes no
+options.
+
 
 #### Transfer
 
@@ -827,20 +849,31 @@ const result = await ctx.noorm.dt.importFile('./exports/users.dtz', {
 
 #### Event Subscriptions
 
-Subscribe to core events via the process-global `noormObserver` bus:
+Subscribe to core events via the process-global `noormObserver` bus. It is a
+singleton, not per-context: if a process calls `createContext()` more than once,
+every context's events flow through it.
 
 ```typescript
-import { noormObserver } from 'noorm/sdk'
+import { noormObserver } from '@noormdev/sdk'
 
 noormObserver.on('file:after', (event) => {
     console.log(`Executed ${event.filepath} in ${event.durationMs}ms`)
 })
 
 noormObserver.on('change:complete', (event) => {
-    console.log(`Change ${event.name}: ${event.status}`)
+    console.log(`Change ${event.name} (${event.direction}): ${event.status}`)
 })
 ```
 
+Event names and payload types are exported as `NoormEventNames` and `NoormEvents`
+(both from `src/core/observer.ts`, which is the authoritative payload list).
+
+Multi-context filtering is only possible on the events that actually carry
+`configName` — `file:before`, `run:*`, `lock:*`, `db:*`, `secret:*`,
+`connection:*`, `sql-terminal:*`, `identity:synced`. Notably `file:after`,
+`change:*`, and `build:*` do **not**, so a process juggling several configs
+cannot attribute those to one of them.
+
 
 ## Use Cases
 
@@ -1020,8 +1053,10 @@ noorm change ff --config dev --json | jq '.status'
 | `db explore tables` | List tables |
 | `db explore tables detail <name>` | Describe a table |
 | `db transfer` | DB-to-DB / export / import (`--to`, `--export`, `--import`) |
-| `change` | List change status |
+| `change list` | List change status (bare `noorm change` renders help) |
 | `change ff` | Apply pending changes |
+| `change next` | Apply the next pending change(s) |
+| `change rewind <name>` | Revert applied changes back to and including `<name>` |
 | `change run <name>` | Apply single change |
 | `change revert <name>` | Revert single change |
 | `change history` | Execution history |
@@ -1057,10 +1092,13 @@ jobs:
         run: |
           npx noorm change ff --config ${{ vars.DB_CONFIG }}
         env:
-          DB_HOST: ${{ secrets.DB_HOST }}
-          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          NOORM_CONNECTION_HOST: ${{ secrets.DB_HOST }}
+          NOORM_CONNECTION_PASSWORD: ${{ secrets.DB_PASSWORD }}
 ```
 
+Only `NOORM_*` variables are read — a bare `DB_HOST` is ignored. See
+[CI/CD Integration](./ci.md) for the full variable list.
+
 
 ## TypeScript Support
 
diff --git a/docs/dev/secrets.md b/docs/dev/secrets.md
index 970578ef..e9fb02b0 100644
--- a/docs/dev/secrets.md
+++ b/docs/dev/secrets.md
@@ -108,14 +108,17 @@ Config-scoped local secret values are managed two ways:
   secrets as suggestions, accepts any key name (UPPER_SNAKE_CASE recommended), masks input
   for password/api_key types, validates connection_string as a URI, and warns before
   overwriting an existing value.
-- **CLI** — `noorm secret set <key> <value>` (`src/cli/secret/set.ts`) writes the same
-  encrypted record headlessly, scoped to the active or `--config`-named config. The value is
-  a positional argument, so unlike the TUI it does land in shell history — reach for the
-  vault instead (below) if that's a concern.
+- **CLI** — `noorm secret set <key> [value]` (`src/cli/secret/set.ts`) writes the same
+  encrypted record headlessly, scoped to the active or `--config`-named config. Passing the
+  value as a positional puts it in shell history *and* in the process table (`ps -ww -eo
+  args`) and in `set -x` CI traces — use `--stdin` instead, which is mutually exclusive with
+  the positional and strips one trailing newline so the `echo` idiom stores the right value.
 
 ```bash
 noorm secret set API_KEY "sk-live-..."
 noorm secret set DB_PASSWORD "secret123" --config prod
+
+echo "$API_KEY" | noorm secret set API_KEY --stdin
 ```
 
 
@@ -167,8 +170,8 @@ instead — team-shared, stored in the database, and reachable from a clean chec
 
 ```bash
 noorm vault set DB_PASSWORD "$DB_PASSWORD"
-echo "$API_KEY" | noorm vault set API_KEY      # Pipe to avoid process listings
-noorm vault list --json                        # Inspect what's stored
+echo "$API_KEY" | noorm vault set API_KEY --stdin      # --stdin is required to read the pipe
+noorm vault list --json                                # Inspect what's stored
 noorm vault rm OLD_API_KEY
 ```
 
@@ -179,22 +182,24 @@ The vault sits below local secrets in the resolution hierarchy (`$.secrets.KEY`
 
 Secrets inject into SQL templates via the `$` context:
 
+noorm's Eta instance uses `{% %}` / `{%~ %}`, not the stock `<% %>` delimiters:
+
 ```sql
 -- sql/users/create-readonly.sql.tmpl
-CREATE USER <%= $.secrets.READONLY_USER %>
-WITH PASSWORD '<%= $.secrets.READONLY_PASSWORD %>';
+CREATE USER {%~ $.secrets.READONLY_USER %}
+WITH PASSWORD '{%~ $.secrets.READONLY_PASSWORD %}';
 
-GRANT SELECT ON ALL TABLES TO <%= $.secrets.READONLY_USER %>;
+GRANT SELECT ON ALL TABLES TO {%~ $.secrets.READONLY_USER %};
 ```
 
 Global secrets use `$.globalSecrets`:
 
 ```sql
 -- Reference app-level secrets
--- API key: <%= $.globalSecrets.SHARED_API_KEY %>
+-- API key: {%~ $.globalSecrets.SHARED_API_KEY %}
 ```
 
-Missing secrets cause template errors at runtime—another reason to set required secrets upfront.
+Reading an unresolved key on `$.secrets` throws `MissingSecretError` naming the key and the tiers searched — it does not render as `undefined`. `$.globalSecrets` is a plain object and does *not* throw. To read an optional secret, probe first: `'KEY' in $.secrets ? $.secrets.KEY : fallback`. See [Template › Secret Access](./template.md#secret-access).
 
 
 ## Stage Matching
@@ -218,10 +223,10 @@ stages:
 ```
 
 ```bash
-noorm config:use prod               # Activates 'prod' config
+noorm config use prod               # Activates 'prod' config
 noorm secret                        # Shows DB_PASSWORD as required
 
-noorm config:use staging            # Activates 'staging' config
+noorm config use staging            # Activates 'staging' config
 noorm secret                        # Shows DB_PASSWORD, DEBUG_KEY as required
 ```
 
@@ -299,12 +304,18 @@ Before running operations, verify a config has all required secrets:
 ```typescript
 import { checkConfigCompleteness } from './core/config'
 
-const check = checkConfigCompleteness(config, state, settings)
+// A required secret satisfied by the vault still counts as set — pass the
+// vault's key names, or a CI runner with no local store reports incomplete.
+const check = checkConfigCompleteness(config, state, settings, {
+    vaultSecretKeys: await listVaultSecretKeys(db, dialect),
+})
 
 if (!check.complete) {
-    console.log('Missing secrets:', check.missingSecrets)
-    // ['DB_PASSWORD', 'READONLY_PASSWORD']
+    console.log('Missing secrets:', check.missingSecrets)  // ['DB_PASSWORD', ...]
+    console.log('Stage violations:', check.violations)
 }
 ```
 
+The fourth argument is optional: `{ stageName?, vaultSecretKeys? }`. `stageName` overrides the stage that would otherwise be inferred from the config name.
+
 The CLI runs this check and prompts users to set missing secrets before proceeding with operations.
diff --git a/docs/dev/settings.md b/docs/dev/settings.md
index 63ca1913..5c7497c7 100644
--- a/docs/dev/settings.md
+++ b/docs/dev/settings.md
@@ -169,6 +169,26 @@ const paths = settings.getPaths()
 ```
 
 
+### Environment overlay
+
+Every accessor returns the **resolved view**: the parsed `settings.yml` document
+plus an overlay of `NOORM_*` environment variables, recomputed after each load
+and each mutation. `NOORM_PATHS_SQL=./ci/sql` therefore changes what
+`getPaths()` returns without touching the file.
+
+The overlay is deliberately kept out of the persisted document — `settings.yml`
+is version controlled, so merging ambient env vars into it would commit whatever
+the shell exported. `save()` writes the document, never the resolved view.
+`NOORM_CONNECTION_*`, `NOORM_IDENTITY_*`, and the behavior variables
+(`NOORM_CONFIG`, `NOORM_YES`, `NOORM_JSON`, `NOORM_HEADLESS`, `NOORM_DEBUG`,
+`NOORM_DEV`, `NOORM_CI_CONFIG_NAME`, `NOORM_LOGGER_DEBUG`, `NOORM_IDENTITY`,
+`NOORM_CHANNEL`) are excluded from it.
+
+The overlay is validated, not re-parsed, so an env value must already have the
+shape the field expects — a scalar where an array is required
+(`NOORM_BUILD_INCLUDE=00_tables`) fails validation rather than being coerced.
+
+
 ## Stage-Based Rules
 
 Rules conditionally include or exclude folders based on the active config's properties. This enables environment-specific behavior without maintaining separate build scripts.
@@ -320,14 +340,20 @@ Defaults provide initial values when creating a config. Users can override most
 | `dialect` | Cannot be changed after creation |
 
 ```typescript
-// Check if stage sets the protected default (the ceiling is applied later, at resolution)
-if (settings.stageEnforcesProtected('prod')) {
-    // This stage's configs get clamped to at most operator/viewer access
-}
-
 // Get stage defaults
 const defaults = settings.getStageDefaults('prod')
 // { dialect: 'postgres', protected: true }
+
+// Read the protected default directly — the ceiling itself is applied later,
+// by resolveConfig. There is no stageEnforcesProtected() helper.
+if (defaults.protected === true) {
+    // This stage's configs get clamped to at most operator/viewer access
+}
+
+// The isTest constraint does have a helper
+if (settings.stageEnforcesIsTest('prod')) {
+    // Configs linked to this stage cannot set isTest: false
+}
 ```
 
 
@@ -479,14 +505,18 @@ These settings are applied automatically when using teardown operations:
 ```typescript
 import { truncateData, teardownSchema } from './core/teardown'
 
+// There is no getTeardown() accessor — read it off the resolved settings object
+const teardown = settings.settings.teardown
+
 // preserveTables from settings are automatically included
 const result = await truncateData(db, dialect, {
-    preserve: settings.getTeardown()?.preserveTables,
+    preserve: teardown?.preserveTables,
 })
 
 // postScript runs after teardown
 const teardownResult = await teardownSchema(db, dialect, {
-    postScript: settings.getTeardown()?.postScript,
+    preserveTables: teardown?.preserveTables,
+    postScript: teardown?.postScript,
 })
 ```
 
@@ -578,8 +608,15 @@ await settings.setLogging({
     file: '.noorm/debug.log'
 })
 
-// Manage universal secrets (required by all stages)
-await settings.addUniversalSecret({ key: 'API_KEY', type: 'env' })
+// Update teardown config
+await settings.setTeardown({
+    preserveTables: ['AppSettings'],
+    postScript: 'sql/teardown/cleanup.sql'
+})
+
+// Manage universal secrets (required by all stages).
+// `type` must be a SecretType: 'string' | 'password' | 'api_key' | 'connection_string'
+await settings.addUniversalSecret({ key: 'API_KEY', type: 'api_key' })
 await settings.updateUniversalSecret('API_KEY', { key: 'API_KEY', type: 'password' })
 await settings.removeUniversalSecret('API_KEY')
 
@@ -624,14 +661,14 @@ import { DEFAULT_SETTINGS, createDefaultSettings } from './core/settings'
 // Read-only reference
 console.log(DEFAULT_SETTINGS)
 // {
-//     build: { include: ['schema'], exclude: [] },
+//     build: { include: [], exclude: [] },   // empty include = all files under paths.sql
 //     paths: { sql: './sql', changes: './changes' },
 //     rules: [],
 //     stages: {},
 //     strict: { enabled: false, stages: [] },
-//     logging: { enabled: true, level: 'info', ... },
-//     teardown: { preserveTables: [], postScript: undefined }
+//     logging: { enabled: true, level: 'info', file: '.noorm/state/noorm.log', maxSize: '10mb', maxFiles: 5 },
 // }
+// No `teardown` key: TeardownConfig is optional and has no defaults.
 
 // Create fresh copy (avoids shared references)
 const fresh = createDefaultSettings()
@@ -724,6 +761,15 @@ observer.on('settings:strict-updated', ({ strict }) => {
 observer.on('settings:logging-updated', ({ logging }) => {
     console.log('Updated logging config')
 })
+
+observer.on('settings:teardown-updated', ({ teardown }) => {
+    console.log('Updated teardown config')
+})
+
+// Secret mutations carry their scope, and the stage name when scope is 'stage'
+observer.on('settings:secret-added', ({ secret, scope, stageName }) => { ... })
+observer.on('settings:secret-updated', ({ key, secret, scope, stageName }) => { ... })
+observer.on('settings:secret-removed', ({ key, scope, stageName }) => { ... })
 ```
 
 
@@ -739,16 +785,16 @@ Settings affect config operations:
 6. **Strict mode** - Requires configs for specified stages
 
 ```typescript
-import { resolveConfig } from './core/config'
+import { resolveConfig, SettingsProvider } from './core/config/resolver'
 import { getSettingsManager } from './core/settings'
 
 const settings = getSettingsManager(process.cwd())
 await settings.load()
 
-// Resolve config with stage defaults
+// resolveConfig takes a SettingsProvider, not the SettingsManager itself.
+// Omit `stage` to auto-link a stage whose name matches the config name.
 const config = resolveConfig(state, {
     name: 'prod',
-    stage: 'prod',
-    settings
+    settings: new SettingsProvider(settings),
 })
 ```
diff --git a/docs/dev/sql-terminal.md b/docs/dev/sql-terminal.md
index 0751a4ce..25340e51 100644
--- a/docs/dev/sql-terminal.md
+++ b/docs/dev/sql-terminal.md
@@ -30,14 +30,17 @@ The SQL terminal provides an interactive REPL for running arbitrary SQL queries.
 
 The terminal executes queries via Kysely's `sql.raw()` and stores history per-config in `.noorm/state/history/`.
 
+Every query passes an access-policy gate first. `executeRawSql` classifies the statement as `read`, `write`, or `ddl` and checks that class against the config's `access` role for the calling channel, so the SDK, CLI, and TUI all inherit one enforcement path.
+
 
 ## Quick Start
 
 ```typescript
 import { executeRawSql, SqlHistoryManager } from './core/sql-terminal'
 
-// Execute a query
-const result = await executeRawSql(db, 'SELECT * FROM users LIMIT 10', 'production')
+// Execute a query — the gate is mandatory
+const gate = { access: config.access, channel: 'user', dialect: 'postgres' }
+const result = await executeRawSql(db, 'SELECT * FROM users LIMIT 10', 'production', gate)
 
 if (result.success) {
     console.log('Columns:', result.columns)
@@ -61,19 +64,26 @@ const savedResult = await history.loadResults(entryId)
 
 ## Executing Queries
 
-The `executeRawSql` function handles any SQL statement:
+The `executeRawSql` function handles any SQL statement. The fourth argument is the `SqlPolicyGate` — `{ access, channel, dialect }` — and it is required:
 
 ```typescript
 import { executeRawSql } from './core/sql-terminal'
+import type { SqlPolicyGate } from './core/sql-terminal'
+
+const gate: SqlPolicyGate = {
+    access: config.access,
+    channel: 'user',
+    dialect: 'postgres',
+}
 
-// SELECT query
+// SELECT query — gated by `sql:read`
 const selectResult = await executeRawSql(db, `
     SELECT id, email, created_at
     FROM users
     WHERE active = true
     ORDER BY created_at DESC
     LIMIT 20
-`, 'production')
+`, 'production', gate)
 
 // {
 //     success: true,
@@ -82,10 +92,10 @@ const selectResult = await executeRawSql(db, `
 //     durationMs: 12
 // }
 
-// INSERT/UPDATE/DELETE
+// INSERT/UPDATE/DELETE — gated by `sql:write`
 const dmlResult = await executeRawSql(db, `
     UPDATE users SET last_login = NOW() WHERE id = 1
-`, 'production')
+`, 'production', gate)
 
 // {
 //     success: true,
@@ -93,10 +103,10 @@ const dmlResult = await executeRawSql(db, `
 //     durationMs: 5
 // }
 
-// DDL statements work too
+// DDL statements work too — gated by `sql:ddl`
 const ddlResult = await executeRawSql(db, `
     CREATE INDEX users_email_idx ON users(email)
-`, 'production')
+`, 'production', gate)
 ```
 
 ### Error Handling
@@ -104,7 +114,7 @@ const ddlResult = await executeRawSql(db, `
 Failed queries return structured error information:
 
 ```typescript
-const result = await executeRawSql(db, 'SELECT * FROM nonexistent', 'dev')
+const result = await executeRawSql(db, 'SELECT * FROM nonexistent', 'dev', gate)
 
 if (!result.success) {
     console.error(result.errorMessage)
@@ -112,6 +122,12 @@ if (!result.success) {
 }
 ```
 
+A policy denial is different: `executeRawSql` **throws** with the policy's blocked reason rather than returning `{ success: false }`. Only the query itself failing produces a result object.
+
+### `executeRawSqlUnchecked`
+
+`src/core/sql-terminal/executor.ts:52` exports an ungated variant that skips classification and runs the SQL directly. It is deliberately left out of the module barrel — import it from `./executor.js` only, and only from tests exercising the Kysely plumbing. No production surface may call it.
+
 
 ## History Management
 
@@ -127,25 +143,27 @@ const history = new SqlHistoryManager('/project', 'production')
 
 ```
 .noorm/
-└── sql-history/
-    ├── production.json                    # History index
-    └── production/
-        ├── abc123-def456.results.gz       # Gzipped results
-        ├── ghi789-jkl012.results.gz
-        └── ...
+└── state/
+    └── history/
+        ├── production.json                # History index
+        └── production/
+            ├── <uuid>.results.gz          # Gzipped results
+            ├── <uuid>.results.gz
+            └── ...
 ```
 
-History entries are stored in JSON. Query results are gzipped separately to keep the index file small.
+History entries are stored in JSON. Query results are gzipped separately to keep the index file small. Both the index and the result files hold verbatim query text and every returned row in the clear, so the manager writes files `0600` and directories `0700` — and re-`chmod`s them on every write, to tighten anything an older version left world-readable.
 
 ### Adding Entries
 
 ```typescript
 // Execute and store
-const result = await executeRawSql(db, 'SELECT * FROM users', 'production')
+const result = await executeRawSql(db, 'SELECT * FROM users', 'production', gate)
 const entryId = await history.addEntry('SELECT * FROM users', result)
 
-// Results are automatically saved to gzipped file
-console.log(entryId)  // "abc123-def456-..."
+// Results are saved to a gzipped file only when the query succeeded and
+// returned at least one row. Otherwise the entry has no `resultsFile`.
+console.log(entryId)  // a UUID v4
 ```
 
 ### Browsing History
@@ -233,7 +251,7 @@ interface ClearResult {
 | Event | Payload | When |
 |-------|---------|------|
 | `sql-terminal:execute:before` | `{ query, configName }` | Before query execution |
-| `sql-terminal:execute:after` | `{ query, configName, success, durationMs, rowCount?, error? }` | After execution |
+| `sql-terminal:execute:after` | success: `{ query, configName, success: true, durationMs, rowCount, rowsAffected }`<br>failure: `{ query, configName, success: false, durationMs, error }` | After execution |
 
 ```typescript
 import { observer } from './core/observer'
@@ -252,12 +270,11 @@ observer.on('sql-terminal:execute:after', ({ success, durationMs, rowCount }) =>
 
 ## CLI Integration
 
-Access the SQL terminal through the database menu:
+`Shift+Q` opens the SQL terminal from anywhere in the TUI — it is a global shortcut, not an entry on the database menu (`d` on the database screen is destroy, `t` is teardown).
 
-1. Press `d` from home to enter database menu
-2. Select a config with an active connection
-3. Press `t` to enter SQL terminal
-4. Type queries and press Enter to execute
+1. Select a config with an active connection
+2. Press `Shift+Q`
+3. Type queries and press Enter to execute
 
 Keyboard shortcuts in terminal:
 
@@ -303,19 +320,21 @@ Long values are truncated with ellipsis. Use the detail view to see full cell co
 
 4. **Clear old history** - Periodically run `clearOlderThan()` to manage storage.
 
-5. **Don't store secrets** - Avoid queries containing sensitive data—history is stored in plaintext (gzipped but not encrypted).
+5. **Don't store secrets** - Avoid queries containing sensitive data—history is stored in plaintext (gzipped and owner-only at `0600`, but not encrypted).
 
 ```typescript
 // Good - verify before delete
 const preview = await executeRawSql(db,
     'SELECT id, email FROM users WHERE last_login < NOW() - INTERVAL 1 YEAR',
-    'production'
+    'production',
+    gate
 )
 console.log(`Would delete ${preview.rows?.length} users`)
 
 // Then execute
 await executeRawSql(db,
     'DELETE FROM users WHERE last_login < NOW() - INTERVAL 1 YEAR',
-    'production'
+    'production',
+    gate
 )
 ```
diff --git a/docs/dev/state.md b/docs/dev/state.md
index c6710318..abe5cfe2 100644
--- a/docs/dev/state.md
+++ b/docs/dev/state.md
@@ -25,7 +25,8 @@ The file contains:
 
 | Field | Purpose |
 |-------|---------|
-| `version` | Schema version for migrations |
+| `version` | Package version that last wrote the file |
+| `schemaVersion` | Numeric state-schema version, keyed to the migrations in `core/version/state` |
 | `knownUsers` | Discovered team members' public keys |
 | `activeConfig` | Currently selected config name |
 | `configs` | Database configurations (credentials included) |
@@ -86,21 +87,20 @@ await state.setConfig('dev', {
         user: 'postgres',
         password: 'postgres',
     },
-    paths: {
-        sql: './sql',
-        changes: './changes',
-    },
 })
+// `paths` is not part of Config — sql/changes locations live in settings.yml
 
 // Retrieve a config
 const dev = state.getConfig('dev')
 
 // List all configs with summary info
 const configs = state.listConfigs()
-// [{ name: 'dev', type: 'local', isTest: false, access: { user: 'admin', agent: 'admin' }, isActive: true }]
+// [{ name: 'dev', type: 'local', isTest: false, access: { user: 'admin', agent: 'admin' },
+//    isActive: true, dialect: 'postgres', database: 'myapp_dev' }]
 
-// Delete a config (also removes its secrets)
-await state.deleteConfig('dev')
+// Delete a config (also removes its secrets).
+// Pass a SettingsProvider to enforce locked-stage protection.
+await state.deleteConfig('dev', settingsProvider)
 ```
 
 
@@ -194,21 +194,23 @@ await state.deleteGlobalSecret('ANTHROPIC_API_KEY')
 
 ### Using Secrets in SQL Templates
 
-Secrets are available in Eta templates via the `$` context:
+Secrets are available in Eta templates via the `$` context. The engine uses
+custom tags — `{%` / `%}`, not Eta's default `<%` / `%>` — and `$` as the
+context variable name:
 
 ```sql
 -- sql/users/create-readonly.sql.tmpl
-CREATE USER <%~ $.secrets.READONLY_USER %>
-WITH PASSWORD '<%~ $.secrets.READONLY_PASSWORD %>';
+CREATE USER {%~ $.secrets.READONLY_USER %}
+WITH PASSWORD '{%~ $.secrets.READONLY_PASSWORD %}';
 
-GRANT SELECT ON ALL TABLES TO <%~ $.secrets.READONLY_USER %>;
+GRANT SELECT ON ALL TABLES TO {%~ $.secrets.READONLY_USER %};
 ```
 
 Global secrets use `$.globalSecrets`:
 
 ```sql
--- Reference app-level secrets
--- <%~ $.globalSecrets.SHARED_API_KEY %>
+INSERT INTO integrations (name, api_key)
+VALUES ('shared', '{%~ $.globalSecrets.SHARED_API_KEY %}');
 ```
 
 
@@ -263,29 +265,53 @@ state.setPrivateKey(yourPrivateKey)
 if (state.hasPrivateKey()) {
     await state.load()
 }
+
+// Re-read ~/.noorm/identity.key from disk — needed when the singleton was
+// constructed before `noorm init` created the identity files
+const loaded = await state.reloadPrivateKey()
 ```
 
+`load()` picks the key up from `~/.noorm/identity.key` on its own when none was
+passed. A new project with no state file loads without a key at all; an existing
+`state.enc` without one throws `Private key required to decrypt state`.
+
 The private key is stored separately in `~/.noorm/identity.key` to solve the bootstrap problem: you need the key to decrypt state, but you can't store the key inside encrypted state.
 
 
 ## Migrations
 
-When the state schema changes between noorm versions, migrations run automatically on load.
+Two independent migration systems run inside `load()`, in this order:
+
+| Order | System | Keyed on | Example |
+|-------|--------|----------|---------|
+| 1 | Schema-version migrations (`core/version/state`) | numeric `schemaVersion` | v2 maps the legacy `protected` boolean to `access` |
+| 2 | Package-semver migration (`core/state/migrations.ts`) | `version` string | backfills missing top-level fields |
+
+The order matters: the semver migration only knows State's own top-level fields
+and would drop anything the schema-version system owns — including
+`schemaVersion` itself — if it ran first.
 
 ```typescript
 await state.load()
-// If version changed:
+// If either migration applied:
 //   - Missing fields get sensible defaults
-//   - state:migrated event emits
-//   - File re-persists with new schema
+//   - state:migrated (semver) / version:state:migrated (schema) events emit
+//   - File re-persists with the new shape
 ```
 
-Migrations are additive - they never delete data, only add missing fields:
+The semver migration carries unknown top-level fields through rather than
+rebuilding from an allowlist — an older binary rebuilding from a fixed list
+silently destroyed fields a newer one had added, and persisted the truncated
+object straight back.
 
-```typescript
-// If 'globalSecrets' field is missing, add it as {}
-// If 'knownUsers' field is missing, add it as {}
-```
+One field is deliberately dropped rather than carried: legacy `identity`. It
+moved to `~/.noorm/`, and pre-move state files hold key material in it, so
+re-persisting would keep a private key inside `state.enc` forever.
+
+`load()` also repairs any config that reached the current schema version without
+a well-formed `access` (a hand-edited file, or one written via `setConfig`
+bypassing the zod path). This is the single place that backfill happens, so no
+downstream consumer needs its own fallback.
 
 
 ## Import/Export
@@ -293,16 +319,19 @@ Migrations are additive - they never delete data, only add missing fields:
 Backup and restore state files while keeping encryption intact.
 
 ```typescript
-// Export (returns encrypted JSON string)
+// Export reads the file back verbatim; null when no state file exists yet
 const backup = state.exportEncrypted()
-fs.writeFileSync('backup.enc', backup)
+
+if (backup) {
+    fs.writeFileSync('backup.enc', backup)
+}
 
 // Import (validates decryption before saving)
-const backup = fs.readFileSync('backup.enc', 'utf8')
-await state.importEncrypted(backup)
+const restored = fs.readFileSync('backup.enc', 'utf8')
+await state.importEncrypted(restored)
 ```
 
-Import validates the file can be decrypted before overwriting. If decryption fails, the current state remains unchanged.
+Import validates the file can be decrypted before overwriting. If decryption fails, the current state remains unchanged. It throws if no private key is available.
 
 
 ## Observer Events
@@ -340,6 +369,18 @@ observer.on('known-user:added', ({ email, source }) => { ... })
 ```
 
 
+## Singleton
+
+Most call sites use the module singleton rather than constructing a manager:
+
+```typescript
+import { getStateManager, initState } from './core/state'
+
+const state = getStateManager(process.cwd())  // construct only; still needs load()
+const loaded = await initState(process.cwd()) // construct + load
+```
+
+
 ## Testing
 
 For tests, use custom paths to avoid polluting the project directory:
diff --git a/docs/dev/teardown.md b/docs/dev/teardown.md
index 1a5d066a..4dd2ff59 100644
--- a/docs/dev/teardown.md
+++ b/docs/dev/teardown.md
@@ -25,6 +25,9 @@ Both operations:
 - Preserve noorm internal tables (`__noorm_*`)
 - Support dry-run mode for preview
 - Generate dialect-specific SQL
+- Take an optional `policy` context, enforced before anything is written
+
+`truncateData` always re-enables FK checks, even when the truncate itself fails partway. A mid-truncate error must never leave enforcement off — MSSQL's per-table `NOCHECK` survives reconnects until manually repaired. When both phases fail, the truncate error is the one thrown; the caller needs to know why the truncate broke, not just that re-enabling also failed.
 
 In SDK terms, `db.truncate()` is the data wipe and `db.reset()` is the schema teardown plus re-run of changes. Reach for `truncate()` between tests when the schema is stable; reach for `reset()` when you want a from-scratch rebuild. See [reference/sdk.md](../reference/sdk.md) for the surface.
 
@@ -91,7 +94,9 @@ console.log('Dropped:')
 console.log(`  Tables: ${result.dropped.tables.length}`)
 console.log(`  Views: ${result.dropped.views.length}`)
 console.log(`  Functions: ${result.dropped.functions.length}`)
+console.log(`  Procedures: ${result.dropped.procedures.length}`)
 console.log(`  Types: ${result.dropped.types.length}`)
+console.log(`  Foreign keys: ${result.dropped.foreignKeys.length}`)
 console.log(`Preserved: ${result.preserved.join(', ')}`)
 ```
 
@@ -100,11 +105,12 @@ console.log(`Preserved: ${result.preserved.join(', ')}`)
 Objects are dropped in dependency-safe order:
 
 1. **Foreign key constraints** - Released first so tables can be dropped later
-2. **Procedures** - Dropped before functions/views/tables they call
-3. **Functions** - Dropped before tables, because schema-bound UDFs (e.g. MSSQL `WITH SCHEMABINDING`) hold dependency locks on the tables they reference. Drop the table first and you get `Cannot DROP TABLE ... because it is being referenced by object 'fn_X'`
-4. **Views** - Same reason as functions; schema-bound views block table drops until they are gone
-5. **Tables** - Safe now that all schema-bound dependents have been removed
-6. **Types** - Enums, composites, and table types (TVPs) drop last
+2. **CHECK constraints** - MSSQL only, and only when `keepFunctions` is false. A scalar UDF referenced by a CHECK constraint cannot be dropped while its table still exists (MSSQL error 3729), and functions are dropped before tables at step 4, so the CHECK dependency has to be severed first. Other dialects omit this step entirely
+3. **Procedures** - Dropped before functions/views/tables they call
+4. **Functions** - Dropped before tables, because schema-bound UDFs (e.g. MSSQL `WITH SCHEMABINDING`) hold dependency locks on the tables they reference. Drop the table first and you get `Cannot DROP TABLE ... because it is being referenced by object 'fn_X'`
+5. **Views** - Same reason as functions; schema-bound views block table drops until they are gone
+6. **Tables** - Safe now that all schema-bound dependents have been removed
+7. **Types** - Enums, composites, and table types (TVPs) drop last. Composites sort ahead of the rest, since they can be referenced by other types and MSSQL's `DROP TYPE` has no `CASCADE`. On MSSQL, types are skipped entirely when `keepFunctions` or `keepProcedures` is set — the dependency chain functions → TVPs → domain types cannot be unwound without `CASCADE`
 
 The order is identical across all dialects. PostgreSQL/MySQL don't strictly require procs/funcs/views to drop before tables — `DROP TABLE ... CASCADE` would handle it — but the same order is correct and harmless, so noorm uses it everywhere for consistency. MSSQL is the dialect that breaks under any other ordering, because it has no `CASCADE` for `DROP TABLE` and schema-bound objects hold real dependency locks.
 
@@ -114,12 +120,15 @@ Keep certain object types:
 
 ```typescript
 const result = await teardownSchema(db, 'postgres', {
-    keepViews: true,      // Preserve all views
-    keepFunctions: true,  // Preserve procedures and functions
-    keepTypes: true,      // Preserve enum and composite types
+    keepViews: true,       // Preserve all views
+    keepFunctions: true,   // Preserve functions only
+    keepProcedures: true,  // Preserve stored procedures — a separate flag
+    keepTypes: true,       // Preserve enum and composite types
 })
 ```
 
+`keepFunctions` and `keepProcedures` are independent. Setting only `keepFunctions` still drops every stored procedure.
+
 Preserve specific tables:
 
 ```typescript
@@ -128,6 +137,25 @@ const result = await teardownSchema(db, 'postgres', {
 })
 ```
 
+Preserve whole schemas. `preserveTables` is a flat name list, so excluding `app_private.secrets` by name would also spare a `public.secrets` — `preserveSchemas` is the way to say "leave this schema alone":
+
+```typescript
+const result = await teardownSchema(db, 'postgres', {
+    preserveSchemas: ['app_private', 'analytics'],
+})
+```
+
+Record the teardown in change history. When both are supplied and this is not a dry run, teardown marks every successful change as `stale` and writes a reset record:
+
+```typescript
+const result = await teardownSchema(db, 'postgres', {
+    configName: 'dev',
+    executedBy: 'alice@example.com',
+})
+
+console.log(`Marked ${result.staleCount} changes stale (record ${result.resetRecordId})`)
+```
+
 ### Post-Teardown Script
 
 Run a cleanup SQL script after teardown:
@@ -184,6 +212,12 @@ interface TruncateOptions {
 
     /** Dry run - return SQL without executing */
     dryRun?: boolean
+
+    /**
+     * Access policy enforced before wiping (`db:truncate`). Omitted by callers
+     * that already ran an equivalent gate; supplied by every caller that owns none.
+     */
+    policy?: DbPolicyContext
 }
 ```
 
@@ -194,12 +228,18 @@ interface TeardownOptions {
     /** Additional tables to preserve beyond __noorm_* */
     preserveTables?: string[]
 
+    /** Schemas to leave untouched entirely */
+    preserveSchemas?: string[]
+
     /** Keep views (default: false) */
     keepViews?: boolean
 
-    /** Keep functions/procedures (default: false) */
+    /** Keep functions (default: false) */
     keepFunctions?: boolean
 
+    /** Keep stored procedures (default: false) */
+    keepProcedures?: boolean
+
     /** Keep types/enums (default: false) */
     keepTypes?: boolean
 
@@ -208,6 +248,15 @@ interface TeardownOptions {
 
     /** Dry run - return SQL without executing */
     dryRun?: boolean
+
+    /** Marks changes stale and records a reset event when set */
+    configName?: string
+
+    /** Identity of who tore down. Required when configName is provided */
+    executedBy?: string
+
+    /** Access policy enforced before dropping (`db:teardown`) */
+    policy?: DbPolicyContext
 }
 ```
 
@@ -226,6 +275,7 @@ interface TeardownResult {
         tables: string[]
         views: string[]
         functions: string[]
+        procedures: string[]
         types: string[]
         foreignKeys: string[]
     }
@@ -236,9 +286,19 @@ interface TeardownResult {
         executed: boolean
         error?: string
     }
+    staleCount?: number       // set when configName + executedBy provided
+    resetRecordId?: number    // set when configName + executedBy provided
+}
+
+interface TeardownPreview {
+    toDrop: TeardownResult['dropped']
+    toPreserve: string[]
+    statements: string[]
 }
 ```
 
+Object names in `dropped` / `preserved` are schema-qualified whenever the object sits outside the dialect's default schema (`public` on PostgreSQL, `dbo` on SQL Server). A bare `secrets` in a dry run would otherwise be indistinguishable from `public.secrets`, hiding the fact that a schema noorm never created is about to be dropped.
+
 
 ## Dialect Support
 
@@ -298,9 +358,9 @@ observer.on('teardown:complete', ({ result }) => {
 
 Access teardown from the database menu:
 
-1. Press `d` from home to enter database menu
+1. Press `d` from home to enter the database screen
 2. Select a config with an active connection
-3. Choose truncate or teardown operation
+3. Press `w` to wipe data (truncate) or `t` to tear down the schema
 4. Confirm the destructive action
 
 The CLI shows a preview of affected objects before execution and requires explicit confirmation for non-dry-run operations.
@@ -309,9 +369,17 @@ The CLI shows a preview of affected objects before execution and requires explic
 ## Safety Features
 
 **Always Preserved:**
+
+Every table whose name starts with `__noorm_` is preserved — that is the whole `isNoormTable` rule, not a fixed list:
+
+- `__noorm_version__` - Schema version tracking
 - `__noorm_change__` - Change execution history
 - `__noorm_executions__` - File execution records
-- `__noorm_locks__` - Active operation locks
+- `__noorm_lock__` - Active operation locks
+- `__noorm_identities__` - Team identities and wrapped vault keys
+- `__noorm_vault__` - Encrypted team secrets
+
+Those are the MySQL/SQLite prefixed names. PostgreSQL and SQL Server keep the same tables in a dedicated `noorm` schema with clean names (`noorm.change`, `noorm.lock`, …), where the prefix rule would never match — they are safe for a different reason: the explore dialects exclude the `noorm` schema from every listing, so teardown never enumerates them in the first place.
 
 **Confirmation Required:**
 - Teardown is gated by the config's access role: `viewer`/`operator` is denied or requires confirmation, `admin` runs unconfirmed
diff --git a/docs/dev/template.md b/docs/dev/template.md
index cdb1dd2d..75dd4ae2 100644
--- a/docs/dev/template.md
+++ b/docs/dev/template.md
@@ -27,9 +27,9 @@ Templates use [Eta](https://eta.js.org/) with custom delimiters. Any `.sql.tmpl`
 When rendering, the engine:
 
 1. Walks up the directory tree collecting `$helpers.ts` files
-2. Scans the template's directory for data files (JSON5, YAML, CSV)
+2. Scans the template's directory for data files (JSON5, YAML, CSV, DT) — skipping executable formats the template doesn't reference
 3. Builds a context object (`$`) with helpers, data, config, and secrets
-4. Renders the template with Eta
+4. Strips `-- {% %}` directive lines, then renders with Eta
 5. Returns the SQL string
 
 
@@ -42,6 +42,11 @@ noorm uses custom delimiters to avoid conflicts with SQL syntax:
 | `{% %}` | JavaScript code block |
 | `{%~ %}` | Output (raw) |
 | `$` | Context variable |
+| `-- {% %}` | Directive line — the whole line is stripped before Eta parses |
+
+The `-- {% ... %}` form keeps a `.sql.tmpl` file valid SQL: directives look like comments to a SQL parser and to your editor's syntax highlighter. The engine strips the `-- ` prefix, trailing whitespace, and the line's newline before rendering, so the directive produces no output. It only matches lines where the tag is the *only* content — `SELECT 1; -- comment` and `-- {% if (x) { %} SELECT 1` are both left alone.
+
+Eta's `autoTrim` is deliberately off; directive-line stripping handles whitespace instead. Enabling `autoTrim` would make `leftTrim` eat the newline after an interpolation tag, turning `{%~ item %}\nAS` into `itemAS`.
 
 ```sql
 -- Loop over data
@@ -80,12 +85,31 @@ File names are converted to camelCase:
 
 ### Supported Formats
 
-| Extension | Loader | Result |
-|-----------|--------|--------|
-| `.json`, `.json5` | JSON5 | Any (supports comments, trailing commas) |
-| `.yaml`, `.yml` | YAML | Any |
-| `.csv` | csv-parse | Array of row objects |
-| `.js`, `.mjs`, `.ts` | Dynamic import | Module default or exports |
+| Extension | Loader | Result | Auto-loaded? |
+|-----------|--------|--------|--------------|
+| `.json`, `.json5` | JSON5 | Any (supports comments, trailing commas) | Yes |
+| `.yaml`, `.yml` | YAML | Any | Yes |
+| `.csv` | csv-parse | Array of row objects | Yes |
+| `.dt`, `.dtz` | DT reader | Rows from a noorm data-transfer file | Yes |
+| `.js`, `.mjs`, `.ts` | Dynamic import | Module default or exports | **Only when referenced** |
+| `.sql` | Raw text | String | No — `.sql` is for `$.include()` only |
+
+The json5, yaml, and csv parsers are lazy-imported on first use, so a project that never loads one of those formats never pulls its parser in.
+
+`.dtzx` has no loader on purpose: a passphrase-encrypted transfer file cannot be decrypted from template context.
+
+
+### Executable data files are not auto-loaded
+
+`.js`, `.mjs`, and `.ts` files execute code when loaded. The engine loads one **only if the template's own source references its context key** — `$.seed` or `$['seed']`. Dropping a script next to a SQL file no longer gets it run.
+
+```sql
+-- seed.ts sits in this directory but is never imported: the template
+-- does not mention $.seed, so nothing executes.
+SELECT 1;
+```
+
+The reference check is syntactic and narrow by design. A false negative costs the author one explicit `$.key` reference; a false positive would re-open the hole where `run preview`, `run inspect`, and `--dry-run` — the three commands whose entire point is *not* to act — silently ran arbitrary code.
 
 
 ### JSON5 Features
@@ -160,8 +184,8 @@ The `$` object contains everything available in templates:
 | Property | Description |
 |----------|-------------|
 | `$.<helper>` | Functions from inherited `$helpers.ts` files |
-| `$.<filename>` | Auto-loaded data from co-located files |
-| `$.config` | Active configuration object |
+| `$.<filename>` | Auto-loaded data from co-located files (data files override helpers of the same name) |
+| `$.config` | Active configuration object — **omitted** when a `config.*` data file sits in the template's directory, which takes the key instead |
 | `$.secrets` | Decrypted secrets for active config. Reading an unresolved key throws `MissingSecretError` naming the key and the tiers searched (config-local, global-local, vault) — see [Secret Access](#secret-access). |
 | `$.globalSecrets` | Decrypted global secrets |
 | `$.env` | Environment variables |
@@ -465,7 +489,9 @@ toContextKey('seed_data.yml')    // 'seedData'
 sqlEscape("O'Reilly")  // "O''Reilly"
 
 // Get supported extensions
-getSupportedExtensions()  // ['.json', '.json5', '.yaml', '.yml', '.csv', '.js', '.mjs', '.ts']
+getSupportedExtensions()
+// ['.json', '.json5', '.yaml', '.yml', '.csv', '.js', '.mjs', '.ts', '.sql', '.dt', '.dtz']
+// `.sql` has a loader (used by $.include) but is skipped during data auto-load.
 
 // Get loader for extension
 const loader = getLoader('.json5')
@@ -478,6 +504,6 @@ const loader = getLoader('.json5')
 
 2. **Secret Exposure** - Secrets are available in templates. The rendered SQL may contain sensitive values - don't log it
 
-3. **JS Execution** - `$helpers.ts` and `.js` data files execute arbitrary code. Only load trusted files
+3. **JS Execution** - `$helpers.ts` files always execute; `.js` / `.mjs` / `.ts` data files execute only when the template references their context key. Both run arbitrary code in the noorm process — with access to the environment, including the identity key. Only load trusted files
 
 4. **Path Traversal** - `$.include()` resolves relative to the template's directory and cannot escape the project root
diff --git a/docs/dev/transfer.md b/docs/dev/transfer.md
index f37c7474..103e357c 100644
--- a/docs/dev/transfer.md
+++ b/docs/dev/transfer.md
@@ -24,15 +24,19 @@ Transfer operates in two phases:
 | Cross-server | Different hosts, same dialect | Batched read from source, write to destination |
 | Cross-dialect | Different dialects | Batched read → type conversion via DtStreamer → write |
 
-Same-server detection varies by dialect:
+Same-server detection varies by dialect (`src/core/transfer/same-server.ts`):
 
 | Dialect | Same-server criteria |
 |---------|---------------------|
-| PostgreSQL | Same host + port + database (no cross-database queries without extensions) |
+| PostgreSQL | **Never** — always takes the batch path |
 | MySQL | Same host + port (cross-database queries supported) |
 | MSSQL | Same host + port (cross-database queries supported) |
 | SQLite | Never (no server concept) |
 
+PostgreSQL is never same-server, and the reason is not just the missing `dblink` / `postgres_fdw`. When both configs name the *same* database, the direct statement degenerates to `INSERT INTO t SELECT ... FROM t` — copying the destination into itself. Neither outcome is a transfer, so postgres has no direct path at all.
+
+Host comparison normalizes `127.0.0.1`, `::1`, and `localhost.localdomain` to `localhost`. An unset port falls back to the dialect's default before comparison, so `host: 'db'` and `host: 'db', port: 3306` are the same server on MySQL.
+
 
 ## Quick Start
 
@@ -90,9 +94,23 @@ interface TransferOptions {
     /** Passphrase for .dtzx export encryption. */
     passphrase?: string
 
+    /** Caller channel for the policy gate. Default: 'user' */
+    channel?: Channel
+
 }
 ```
 
+### Policy gates
+
+Both entry points are gated against the **destination** config — the write target is the destructive side, not the source:
+
+| Function | Permission | Notes |
+|----------|-----------|-------|
+| `transferData` | `db:reset` | Checked before any connection opens. Dry runs are gated too — the matrix has no carve-out |
+| `getTransferPlan` | `transfer:plan` | The plan is destination schema metadata (table names, row estimates, the FK graph). Ungated, a viewer denied `transferData` could read all of it through `--dry-run` |
+
+A denial is returned as the error half of the tuple, not thrown.
+
 
 ## Conflict Strategies
 
@@ -100,12 +118,16 @@ When the destination already has rows with matching primary keys:
 
 | Strategy | Behavior | PostgreSQL | MySQL | MSSQL |
 |----------|----------|------------|-------|-------|
-| `fail` | Abort on first conflict | Default insert | Default insert | Default insert |
-| `skip` | Skip conflicting rows | `ON CONFLICT DO NOTHING` | `INSERT IGNORE` | `MERGE ... WHEN NOT MATCHED` |
-| `update` | Update existing rows | `ON CONFLICT DO UPDATE` | `ON DUPLICATE KEY UPDATE` | `MERGE ... WHEN MATCHED UPDATE` |
-| `replace` | Delete and re-insert | Row-by-row fallback | `REPLACE INTO` | `MERGE ... DELETE + INSERT` |
+| `fail` | Abort on first conflict | Plain insert | Plain insert | Plain insert |
+| `skip` | Skip conflicting rows | `ON CONFLICT (pk) DO NOTHING` | `INSERT IGNORE` | `MERGE ... WHEN NOT MATCHED INSERT` |
+| `update` | Update non-PK columns | `ON CONFLICT (pk) DO UPDATE SET` | `ON DUPLICATE KEY UPDATE` | `MERGE ... WHEN MATCHED UPDATE / WHEN NOT MATCHED INSERT` |
+| `replace` | Overwrite the whole row | `ON CONFLICT (pk) DO UPDATE SET` (all columns) | `REPLACE INTO` | `MERGE`, updating all columns when matched |
+
+`replace` only literally deletes and re-inserts on MySQL, where `REPLACE INTO` is defined that way — with the side effects that implies (`ON DELETE CASCADE` fires, unlisted columns reset to defaults). PostgreSQL and MSSQL implement it as an upsert over every column, so the row is overwritten in place.
+
+When *all* columns are part of the primary key there is nothing to update, so `update` degrades to `DO NOTHING` on PostgreSQL and `INSERT IGNORE` on MySQL.
 
-The `fail` strategy uses the same-server direct path when available. Other strategies always use the cross-server batch path, even on the same server, because conflict handling requires row-level control.
+The `fail` strategy uses the same-server direct path when available. Other strategies always use the cross-server batch path, even on the same server, because conflict handling requires row-level control. A cross-dialect transfer never uses the direct path regardless of strategy.
 
 
 ## Planning
@@ -126,7 +148,9 @@ For each table, the planner collects:
 - Foreign key relationships
 - Estimated row count
 
-Internal tables (`__noorm_*`) are automatically excluded.
+Internal tables are excluded by **name prefix only** — `listUserTables` drops anything starting with `__noorm_` (`src/core/transfer/planner.ts:249`).
+
+> **Caveat on PostgreSQL and SQL Server.** Those dialects keep their tracking tables in a dedicated `noorm` schema under clean names (`noorm.change`, `noorm.lock`, …), which the `__noorm_` prefix test does not match. Unlike the explore and teardown paths, the transfer planner's catalog queries exclude only the true system schemas (`pg_catalog` / `information_schema` / `pg_toast`, and `is_ms_shipped = 0` on MSSQL), so noorm's own tracking tables can appear in a plan. Check the dry-run table list, or pass `--tables` explicitly, before transferring a whole PostgreSQL or SQL Server database.
 
 ### FK Dependency Ordering
 
@@ -176,7 +200,7 @@ When `preserveIdentity` is true (default):
 
 | Dialect | Enable | Disable | Sequence Reset |
 |---------|--------|---------|----------------|
-| PostgreSQL | Not needed (SERIAL/GENERATED BY DEFAULT) | — | `SELECT setval(pg_get_serial_sequence(...), MAX(col))` |
+| PostgreSQL | Not needed — every insert carries `OVERRIDING SYSTEM VALUE`, which is what lets `GENERATED ALWAYS AS IDENTITY` accept an explicit value | — | `SELECT setval(pg_get_serial_sequence(...), MAX(col))` |
 | MySQL | Not needed (AUTO_INCREMENT allows explicit values) | — | `ALTER TABLE ... AUTO_INCREMENT = MAX(col) + 1` |
 | MSSQL | `SET IDENTITY_INSERT table ON` | `SET IDENTITY_INSERT table OFF` | `DBCC CHECKIDENT(table, RESEED)` |
 
@@ -196,9 +220,13 @@ Foreign key checks are disabled on the destination before transfer and re-enable
 
 | Dialect | Disable | Enable |
 |---------|---------|--------|
-| PostgreSQL | `ALTER TABLE ... DISABLE TRIGGER ALL` (per table) | `ALTER TABLE ... ENABLE TRIGGER ALL` |
+| PostgreSQL | `SET session_replication_role = replica` (session-wide) | `SET session_replication_role = DEFAULT` |
 | MySQL | `SET FOREIGN_KEY_CHECKS = 0` (session-wide) | `SET FOREIGN_KEY_CHECKS = 1` |
-| MSSQL | `ALTER TABLE ... NOCHECK CONSTRAINT ALL` (per table) | `ALTER TABLE ... CHECK CONSTRAINT ALL` |
+| MSSQL | `ALTER TABLE ... NOCHECK CONSTRAINT ALL` (per table) | `ALTER TABLE ... WITH CHECK CHECK CONSTRAINT ALL` (per table) |
+
+PostgreSQL's `session_replication_role` suppresses all trigger-based constraint checking, foreign keys included, for the session — it is not a per-table `DISABLE TRIGGER`. It requires superuser (or an equivalent grant); on a locked-down role the transfer will fail at the disable step rather than silently proceeding unprotected.
+
+MSSQL's re-enable uses `WITH CHECK CHECK`, not a bare `CHECK` — the extra `WITH CHECK` re-validates the rows inserted while the constraint was off, so the constraint comes back trusted instead of merely enabled.
 
 If the post-transfer re-enable fails, the transfer itself still completes, but `TransferResult.fkChecksRestored` is `false` and the CLI prints a warning. Re-enable FK checks manually before trusting referential integrity on the destination.
 
@@ -225,8 +253,8 @@ The `DtStreamer` converts between dialect types through a universal intermediate
 
 | Category | Universal Types |
 |----------|-----------------|
-| Simple | `string`, `int`, `bigint`, `float`, `decimal`, `bool`, `timestamp`, `date`, `uuid` |
-| Encoded | `json`, `binary`, `vector`, `array`, `custom` |
+| Simple (native JSON values) | `string`, `int`, `bigint`, `float`, `decimal`, `bool`, `timestamp`, `date`, `uuid` |
+| Encoded (`[value, encoding]` tuples) | `json`, `binary`, `vector`, `array`, `text`, `custom` |
 
 Version-aware mappings handle dialect differences:
 
@@ -320,24 +348,44 @@ const [importResult, importErr] = await importDtFile({
 
 `.dtzx` files use passphrase-based encryption:
 
-- Key derivation: PBKDF2 with random salt
-- Cipher: AES-256-GCM with random IV
+- Key derivation: PBKDF2-SHA256, 100,000 iterations, 32-byte random salt, 32-byte key
+- Cipher: AES-256-GCM, 16-byte random IV, 16-byte auth tag
 - Format: `{ salt, iv, authTag, ciphertext }` (all base64)
+- Minimum passphrase length: 12 characters, enforced on **encryption only** — a floor on decryption would brick archives written by older versions, and a wrong passphrase already fails at the GCM tag
 
 The encryption is self-contained—no dependency on noorm's identity system. Files can be shared and decrypted anywhere with the passphrase.
 
+### Decompression bounds
+
+`.dt` content is untrusted — it arrives from a colleague, a bucket, or a CI artifact — and gzip reaches roughly 1000:1 on repetitive input. The reader caps expansion rather than discovering the problem as an OOM:
+
+| Limit | Value | Applies to |
+|-------|-------|------------|
+| `MAX_DECOMPRESSED_VALUE_BYTES` | 64 MB | A single gzipped column value |
+| `MAX_DECOMPRESSED_ARCHIVE_BYTES` | 1 GB | A whole `.dtzx` archive — it is decrypted and inflated before any row is read, so the entire thing is resident |
+| `MAX_ROW_BYTES` | 256 MB | One line in a `.dt` stream — readline buffers until it finds a newline, so a file with no newlines is the same exhaustion vector by another route |
+
+`.dt` and `.dtz` stream, so only the per-value and per-line caps apply to them.
+
 ### Template Loader Integration
 
-`.dt` and `.dtz` files work as seed data in templates:
+`.dt` and `.dtz` files work as seed data in templates. There is no `load()` helper — the file is auto-loaded by filename into the `$` context like any other data file, as an array of row objects:
+
+```
+seeds/
+├── users.sql.tmpl
+└── users.dt        → $.users
+```
 
 ```sql
--- seeds/users.sql
-<% const users = await load('./users.dt') %>
-<% for (const row of users) { %>
-INSERT INTO users (id, email) VALUES (<%= row.id %>, '<%= row.email %>');
-<% } %>
+-- seeds/users.sql.tmpl
+{% for (const row of $.users) { %}
+INSERT INTO users (id, email) VALUES ({%~ row.id %}, {%~ $.quote(row.email) %});
+{% } %}
 ```
 
+The loader reads the schema header for column names and maps each row's positional values to named fields, so `$.users[0].email` works without you naming the columns.
+
 Note: `.dtzx` files are not supported in templates—there's no secure way to provide the passphrase.
 
 
@@ -348,6 +396,12 @@ Each dialect implements the `TransferDialectOperations` interface:
 ```typescript
 interface TransferDialectOperations {
 
+    /** Session-level SQL to disable FK checks (PG/MySQL; MSSQL works per table) */
+    getDisableFKSql(): string
+
+    /** Session-level SQL to re-enable FK checks */
+    getEnableFKSql(): string
+
     /** SQL to enable identity insert for a table */
     getEnableIdentityInsertSql(table: string): string | null
 
@@ -490,7 +544,7 @@ interface TransferTableResult {
 | `transfer:table:before` | `{ table, index, total, rowCount }` | Before each table |
 | `transfer:table:progress` | `{ table, rowsTransferred, rowsTotal, rowsSkipped }` | During batch transfers |
 | `transfer:table:after` | `{ table, status, rowsTransferred, rowsSkipped, durationMs, error? }` | After each table |
-| `transfer:complete` | `{ status, totalRows, tableCount, durationMs }` | Transfer finished |
+| `transfer:complete` | `{ status, totalRows, tableCount, durationMs, fkChecksRestored }` | Transfer finished |
 
 ### Export/Import Events
 
@@ -504,6 +558,29 @@ interface TransferTableResult {
 | `dt:import:progress` | `{ filepath, table, rowsImported, rowsSkipped }` | After each batch insert |
 | `dt:import:complete` | `{ filepath, table, rowsImported, rowsSkipped, durationMs }` | Import finished |
 
+`dt:import:schema` reports `columns` as a **count**, not the column list.
+
+### Worker Pipeline Events
+
+Export and import run through the three-tier worker pipeline (connection worker → compute pool → order buffer), which emits its own per-stage counters:
+
+| Event | Payload | When |
+|-------|---------|------|
+| `dt:export:loaded` | `{ table, loaded, totalRows }` | A batch arrived from the connection worker |
+| `dt:export:processed` | `{ table, processed, totalRows }` | A compute worker finished serializing rows |
+| `dt:export:saved` | `{ table, saved, totalRows }` | The order buffer flushed consecutive rows to `DtWriter` |
+| `dt:import:loaded` | `{ table, loaded, totalRows }` | A batch of lines was read by `DtReader` |
+| `dt:import:processed` | `{ table, processed, totalRows }` | A compute worker finished deserializing rows |
+| `dt:import:saved` | `{ table, saved, totalRows }` | Deserialized rows were inserted |
+
+### Modify Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `dt:modify:start` | `{ inputPath, outputPath, recipeLength }` | Modify begins |
+| `dt:modify:progress` | `{ rowsRead, rowsWritten, rowsFiltered }` | After each row |
+| `dt:modify:complete` | `{ result }` | Modify finished |
+
 ### Cross-Dialect Stream Events
 
 | Event | Payload | When |
@@ -558,7 +635,7 @@ From the database menu, the transfer screen provides a wizard with three modes:
 5. Set conflict strategy
 6. Execute with progress
 
-Access via: Home → `d` (database) → select config → transfer option
+Access via: Home → `d` (database) → select config → `r` (transfer)
 
 ### Headless Mode
 
@@ -584,7 +661,10 @@ noorm db transfer --to backup --json
 # Export single table to .dt file
 noorm db transfer --export ./backup/users.dt --tables users
 
-# Export multiple tables to directory (compressed)
+# Export every table to a directory (compressed) — --tables defaults to all
+noorm db transfer --export ./backup/ --compress
+
+# Export multiple named tables to a directory
 noorm db transfer --export ./backup/ --tables users,posts --compress
 
 # Export with encryption
@@ -602,14 +682,17 @@ noorm db transfer --import ./backup.dt --dry-run
 
 ### Export Path Rules
 
-The `--tables` flag is required for export. The `--export` path is interpreted based on table count:
+`--tables` defaults to every user table. Passing it *explicitly empty* is an error rather than a no-op — an export that wrote nothing, reported success, and exited 0 is a silent empty backup.
+
+The `--export` path is interpreted based on how many tables resolve:
 
 | Scenario | Path | Result |
 |----------|------|--------|
 | Single table | `./data/users.dt` | Writes to that exact path |
-| Multiple tables | `./data/backup/` | Creates `<table>.dt` per table |
+| Single table | `./data/users` | Appends the flag-derived extension |
+| Multiple tables | `./data/backup/` | Creates `<table><ext>` per table |
 
-Extension determines format when specified explicitly. Otherwise:
+An explicit `.dt` / `.dtz` / `.dtzx` suffix is honoured only in the single-table case. In multi-table mode the extension always comes from the flags:
 
 | Flags | Output Extension |
 |-------|------------------|
@@ -617,6 +700,8 @@ Extension determines format when specified explicitly. Otherwise:
 | `--compress` | `.dtz` |
 | `--passphrase` | `.dtzx` |
 
+Exporting to `.dtzx` without `--passphrase` prompts for one (masked, minimum 12 characters). In a non-TTY session or with `--json`, the prompt is impossible and the command exits with a usage error instead — pass `--passphrase` in CI.
+
 
 ## Module Structure
 
@@ -649,7 +734,9 @@ src/core/dt/
 ├── schema.ts           # buildDtSchema(), validateSchema()
 ├── version.ts          # queryDatabaseVersion()
 ├── crypto.ts           # encryptWithPassphrase(), decryptWithPassphrase()
-├── paths.ts            # resolveExportPath(), resolveExportExtension()
+├── modify.ts           # modifyDtFile(), transformSchema(), validateRecipe()
+├── paging.ts           # Paged row reads for large files
+├── paths.ts            # resolveExportPath(), resolveExportExtension(), resolveExportTables()
 └── dialects/
     ├── index.ts        # Dialect registry
     ├── postgres.ts     # PostgreSQL type mappings
@@ -666,7 +753,7 @@ src/core/dt/
 
 3. **Row-by-row conflict handling** — Cross-server and cross-dialect transfers with conflict strategies insert rows individually rather than in bulk, which is slower for large datasets with many conflicts.
 
-4. **PostgreSQL cross-database** — PostgreSQL cannot query across databases without the `dblink` or `postgres_fdw` extensions. Same-server optimization only applies when both configs point to the same database.
+4. **No same-server path on PostgreSQL** — PostgreSQL cannot query across databases without `dblink` / `postgres_fdw`, and pointing both configs at the *same* database would make the direct statement copy a table into itself. Every PostgreSQL transfer therefore uses the batched path, even between two databases on one server.
 
 5. **Type conversion fidelity** — Cross-dialect transfers convert through universal types. Some dialect-specific features may be lost (e.g., PostgreSQL arrays become JSON in MySQL, custom types become strings). The schema validation warns about potential issues before transfer begins.
 
diff --git a/docs/dev/vault.md b/docs/dev/vault.md
index 2e336fc4..228a8920 100644
--- a/docs/dev/vault.md
+++ b/docs/dev/vault.md
@@ -105,28 +105,38 @@ Stored as JSON in the `encrypted_value` column. Each secret has its own random I
 
 ## Database Schema
 
-Two database changes support the vault:
+Two tables back the vault, and both are created by schema migration v1 (`src/core/version/schema/migrations/v1.ts`) — there is no separate "add vault" migration.
 
-### `__noorm_vault__` Table
+Table names below are the MySQL/SQLite prefixed form. PostgreSQL and SQL Server store these in a dedicated `noorm` schema instead (`noorm.vault`, `noorm.identities`), with no prefix.
+
+### Vault Table (`__noorm_vault__`)
 
 ```sql
 CREATE TABLE __noorm_vault__ (
-    id              INT PRIMARY KEY,
+    id              INT PRIMARY KEY,   -- serial (PG) / identity(1,1) (MSSQL) / autoincrement
     secret_key      VARCHAR(255) NOT NULL UNIQUE,
     encrypted_value TEXT NOT NULL,
     set_by          VARCHAR(255) NOT NULL,
-    created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-    updated_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+    created_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
+
+CREATE INDEX idx_vault_secret_key ON __noorm_vault__ (secret_key);
 ```
 
+The `id` column is dialect-dependent: `serial` on PostgreSQL, `int identity(1,1)` on SQL Server, `integer primary key autoincrement` elsewhere. `created_at` / `updated_at` use `datetime2` on SQL Server (its `timestamp` is a binary rowversion counter, not a datetime) and `timestamp` everywhere else. Every one of these datetime columns is *naive* — it stores a wall clock with no offset.
+
 The `encrypted_value` column stores JSON: `{ iv, authTag, ciphertext }`.
 
-### `__noorm_identities__` Extension
+Secret keys must match `/^[A-Za-z][A-Za-z0-9_]*$/` — the same regex `StateManager.setSecret` enforces, because vault and local state feed the same `$.secrets` template namespace. A key one writer accepts and the other rejects resolves in one environment and not the other.
+
+### Identities Table (`__noorm_identities__`)
+
+The vault key column is part of the identities table from creation:
 
 ```sql
-ALTER TABLE __noorm_identities__
-ADD COLUMN encrypted_vault_key TEXT;
+-- excerpt from the v1 CREATE TABLE
+encrypted_vault_key TEXT   -- nullable
 ```
 
 When this column is NULL, the user hasn't received vault access yet. After propagation, it contains their encrypted copy of the vault key.
@@ -145,8 +155,9 @@ async function resolveSecret(
     stateManager: StateManager,
     configName: string,
     secretKey: string,
-    db?: Kysely<NoormDatabase>,
-    vaultKey?: Buffer,
+    db?: Kysely<NoormDatabase> | null,
+    vaultKey?: Buffer | null,
+    dialect?: Dialect,          // defaults to 'postgres' when omitted
 ): Promise<string | null> {
 
     // 1. Config-specific local
@@ -159,28 +170,33 @@ async function resolveSecret(
 
     // 3. Vault
     if (db && vaultKey) {
-        return getVaultSecret(db, vaultKey, secretKey);
+        return getVaultSecret(db, vaultKey, secretKey, dialect ?? 'postgres');
     }
 
     return null;
 }
 ```
 
+Every storage-layer function takes `dialect` as its last argument — it selects between the prefixed and schema-qualified table names. Omitting it against MySQL or SQLite looks in a `noorm` schema those dialects don't have.
+
+`resolveVaultKey(db, dialect)` is the helper that loads the on-disk identity, reads the private key, and returns the vault key — degrading to `null` on any failure. A project with no vault at all keeps working.
+
 For template rendering, `buildSecretsContext()` merges all three layers with proper priority:
 
 ```typescript
 async function buildSecretsContext(
     stateManager: StateManager,
     configName: string,
-    db?: Kysely<NoormDatabase>,
-    vaultKey?: Buffer,
+    db?: Kysely<NoormDatabase> | null,
+    vaultKey?: Buffer | null,
+    dialect?: Dialect,
 ): Promise<Record<string, string>> {
 
     const secrets: Record<string, string> = {};
 
     // 1. Start with vault (lowest priority)
     if (db && vaultKey) {
-        const vaultSecrets = await getAllVaultSecrets(db, vaultKey);
+        const vaultSecrets = await getAllVaultSecrets(db, vaultKey, dialect ?? 'postgres');
         for (const [key, secret] of Object.entries(vaultSecrets)) {
             secrets[key] = secret.value;
         }
@@ -222,6 +238,7 @@ async function initializeVault(
     db: Kysely<NoormDatabase>,
     identityHash: string,
     publicKey: string,
+    dialect: Dialect,
 ): Promise<[Buffer | null, Error | null]> {
 
     // Check if already initialized
@@ -276,44 +293,66 @@ else {
 
 ### Propagation
 
-Users with vault access can propagate to pending users:
+Users with vault access can propagate to pending users. `options.targets` restricts the grant to specific identity hashes; omitting it grants to every identity currently without access.
 
 ```typescript
 async function propagateVaultKey(
     db: Kysely<NoormDatabase>,
     vaultKey: Buffer,
+    dialect: Dialect,
+    options: { targets?: string[] } = {},
 ): Promise<VaultPropagationResult> {
 
-    // Find users without access
-    const users = await db
-        .selectFrom('__noorm_identities__')
-        .select(['identity_hash', 'public_key', 'email'])
-        .where('encrypted_vault_key', 'is', null)
-        .execute();
+    // Find users without access — tuple-returning, so "nobody is waiting"
+    // and "the query failed" stay distinguishable
+    const [pending, err] = await getUsersWithoutVaultAccess(db, dialect);
+    if (err) throw err;
+
+    const users = options.targets
+        ? pending.filter((u) => options.targets?.includes(u.identityHash))
+        : pending;
 
     const propagatedTo: string[] = [];
+    const failed: FailedVaultPropagation[] = [];
 
     for (const user of users) {
         // Encrypt vault key for this user's public key
-        const encrypted = encryptVaultKey(vaultKey, user.public_key);
+        const encrypted = encryptVaultKey(vaultKey, user.publicKey);
 
-        await db
+        const [, updateErr] = await attempt(() => db
             .updateTable('__noorm_identities__')
             .set({ encrypted_vault_key: JSON.stringify(encrypted) })
-            .where('identity_hash', '=', user.identity_hash)
-            .execute();
+            .where('identity_hash', '=', user.identityHash)
+            .execute());
+
+        if (updateErr) {
+            failed.push({ identityHash: user.identityHash, email: user.email, error: updateErr.message });
+            continue;
+        }
 
-        propagatedTo.push(user.identity_hash);
+        propagatedTo.push(user.identityHash);
         observer.emit('vault:propagated', {
-            toIdentityHash: user.identity_hash,
+            toIdentityHash: user.identityHash,
             toEmail: user.email,
         });
     }
 
-    return { propagatedTo, alreadyHadAccess: totalWithAccess - propagatedTo.length };
+    return { propagatedTo, alreadyHadAccess: totalWithAccess - propagatedTo.length, failed };
 }
 ```
 
+**A non-empty `failed` is an error, not a warning.** A grant that silently skipped a teammate left both parties believing access had been handed over. Callers must check it:
+
+```typescript
+const result = await propagateVaultKey(db, vaultKey, 'postgres', { targets: [hash] });
+
+if (result.failed.length > 0) {
+    throw new Error('partial propagation');
+}
+```
+
+`propagateVaultKeyTo(db, vaultKey, targetIdentityHash, dialect)` grants to exactly one user and returns a boolean — `true` also when the user already had access.
+
 
 ### Cross-Config Copy
 
@@ -327,40 +366,67 @@ async function copyVaultSecrets(
     identityHash: string,
     privateKey: string,
     publicKey: string,
-    options: { force?: boolean },
+    options: VaultCopyOptions = {},
 ): Promise<[VaultCopyResult | null, Error | null]> {
 
+    const { force = false, channel = 'user', dryRun = false } = options;
+
+    // Gated here rather than in `vault cp`: this function holds both configs,
+    // so every surface that reaches it inherits the check.
+    assertVaultPolicy({ configName: sourceConfig.name, access: sourceConfig.access, channel }, 'vault:read');
+    if (!dryRun) {
+        assertVaultPolicy({ configName: destConfig.name, access: destConfig.access, channel }, 'vault:write');
+    }
+
     return withDualConnection({ sourceConfig, destConfig }, async (ctx) => {
 
         // Get source vault key
-        const sourceVaultKey = await getVaultKey(ctx.source.db, identityHash, privateKey);
+        const sourceVaultKey = await getVaultKey(ctx.source.db, identityHash, privateKey, ctx.source.dialect);
         if (!sourceVaultKey) throw new Error('No vault access on source');
 
-        // Initialize or access destination vault
-        const destStatus = await getVaultStatus(ctx.destination.db, identityHash);
-        let destVaultKey: Buffer;
+        // Initialize or access destination vault. A dry run never creates one.
+        const destStatus = await getVaultStatus(ctx.destination.db, identityHash, ctx.destination.dialect);
+        let destVaultKey: Buffer | null;
 
         if (!destStatus.isInitialized) {
-            const [newKey] = await initializeVault(ctx.destination.db, identityHash, publicKey);
-            destVaultKey = newKey!;
+            destVaultKey = dryRun
+                ? null
+                : (await initializeVault(ctx.destination.db, identityHash, publicKey, ctx.destination.dialect))[0];
+        } else if (!destStatus.hasAccess) {
+            throw new Error('No vault access on destination');
         } else {
-            destVaultKey = await getVaultKey(ctx.destination.db, identityHash, privateKey);
+            destVaultKey = await getVaultKey(ctx.destination.db, identityHash, privateKey, ctx.destination.dialect);
         }
 
         // Copy secrets
-        const allSourceSecrets = await getAllVaultSecrets(ctx.source.db, sourceVaultKey);
+        const allSourceSecrets = await getAllVaultSecrets(ctx.source.db, sourceVaultKey, ctx.source.dialect);
         const result: VaultCopyResult = { copied: [], skipped: [], errors: [] };
 
         for (const [key, secret] of Object.entries(allSourceSecrets)) {
             if (keys !== 'all' && !keys.includes(key)) continue;
 
-            const exists = await vaultSecretExists(ctx.destination.db, key);
-            if (exists && !options.force) {
+            const exists = destStatus.isInitialized
+                ? await vaultSecretExists(ctx.destination.db, key, ctx.destination.dialect)
+                : false;
+
+            if (exists && !force) {
                 result.skipped.push(key);
                 continue;
             }
 
-            await setVaultSecret(ctx.destination.db, destVaultKey, key, secret.value, `copied from ${sourceConfig.name}`);
+            if (dryRun) {
+                result.copied.push(key);
+                continue;
+            }
+
+            await setVaultSecret(
+                ctx.destination.db,
+                destVaultKey as Buffer,
+                key,
+                secret.value,
+                `copied from ${sourceConfig.name}`,
+                ctx.destination.dialect,
+            );
             result.copied.push(key);
         }
 
@@ -369,6 +435,39 @@ async function copyVaultSecrets(
 }
 ```
 
+`VaultCopyOptions` carries three fields:
+
+| Field | Default | Effect |
+|-------|---------|--------|
+| `force` | `false` | Overwrite secrets that already exist in the destination |
+| `channel` | `'user'` | Who is asking; gates the source read and the destination write |
+| `dryRun` | `false` | Run the full preflight — vault access on both ends, source-key existence, destination collisions — and write nothing |
+
+A dry run reports the same `copied` / `skipped` / `errors` the real run would produce. Keys named in `keys` but missing from the source vault land in `result.errors`, not silently dropped.
+
+
+## Policy Gating
+
+The functions above take no config, so they cannot consult `access`. They are the ungated primitives the TUI still calls directly. **Every surface that holds a config — CLI, SDK — must use the `*Checked` wrappers instead**, which is what closes the hole where a `viewer`-role config could still write the vault:
+
+| Ungated | Gated wrapper | Permission |
+|---------|---------------|------------|
+| `initializeVault` | `initializeVaultChecked` | `vault:write` |
+| `getVaultKey` | `getVaultKeyChecked` | `vault:read` |
+| `setVaultSecret` | `setVaultSecretChecked` | `vault:write` |
+| `deleteVaultSecret` | `deleteVaultSecretChecked` | `vault:write` |
+| `listVaultSecretKeys` | `listVaultSecretKeysChecked` | `vault:read` |
+| `propagateVaultKey` | `propagateVaultKeyChecked` | `vault:propagate` |
+| `propagateVaultKeyTo` | `propagateVaultKeyToChecked` | `vault:propagate` |
+
+Each wrapper takes a `VaultPolicyGate` (`{ configName, access, channel }`) as its first argument and throws with the policy's `blockedReason` when denied. `access` is optional only so a caller holding partial config JSON can pass what it has — an absent `access` denies rather than waves through.
+
+`assertVaultPolicy` ignores `requiresConfirmation`, because the core has no way to ask. Surfaces that must distinguish "denied" from "allowed but needs confirmation" — `vault:write` and `vault:propagate` are confirm cells for the `operator` role — call `checkVaultPolicy(gate, permission)` first and resolve the prompt themselves.
+
+Gating `getVaultKey` rather than each individual read is what makes the gate hard to route around: `getVaultSecret` and `getAllVaultSecrets` are useless without the key, so a denied caller cannot decrypt anything. `listVaultSecretKeys` is gated even though it decrypts nothing — key names alone enumerate which systems the team holds credentials for.
+
+`getVaultStatus` has no gated twin on purpose: it returns counts and booleans, never key names or values, and callers need it to tell a user *why* they have no access.
+
 
 ## CLI Commands
 
@@ -380,7 +479,7 @@ Initialize the vault for the active config's database:
 noorm vault init
 ```
 
-Creates a new vault key and stores it encrypted for your identity. Fails if vault already initialized.
+Creates a new vault key and stores it encrypted for your identity. Re-running it is safe: if the vault is already initialized and you have access, it reports success and does nothing. It fails only when the vault exists and *you* have no access — the fix there is `vault propagate` from a teammate, not another `init`.
 
 
 ### `vault set`
@@ -390,6 +489,10 @@ Store a secret in the vault:
 ```bash
 noorm vault set API_KEY "sk-live-..."
 noorm vault set DB_PASSWORD "secret123"
+
+# Keep the value out of argv, the process table, and shell history.
+# One trailing newline is stripped, so the plain `echo` idiom is safe.
+echo "$API_KEY" | noorm vault set API_KEY --stdin
 ```
 
 Upserts—creates new or updates existing. Records `set_by` for audit trail.
@@ -421,22 +524,25 @@ Grant vault access to pending team members:
 
 ```bash
 noorm vault propagate
+noorm vault propagate --to <hash>,<hash>   # Only these identity hashes
 ```
 
-Encrypts the vault key for each user's public key.
+Encrypts the vault key for each user's public key. Without `--to` it grants to every identity currently awaiting access — a grant that cannot be revoked, so prefer naming targets. Passing a hash that isn't awaiting access is an error, not a silent skip. Under the `operator` role the command requires `--yes`.
 
 
 ### `vault cp`
 
-Copy secrets between configs:
+Copy a secret between configs. All three positionals — key, source, destination — are required; there is no "copy every secret" CLI form (the `keys: 'all'` mode exists only on the `copyVaultSecrets` SDK function):
 
 ```bash
-noorm vault cp API_KEY staging production    # Copy one secret
-noorm vault cp staging production            # Copy all secrets
-noorm vault cp --force staging production    # Overwrite existing
-noorm vault cp --dry-run staging production  # Preview only
+noorm vault cp API_KEY staging production               # Copy one secret
+noorm vault cp DB_PASSWORD dev staging --force          # Overwrite existing
+noorm vault cp API_KEY staging production --dry-run     # Preview only
+noorm vault cp API_KEY staging production --json
 ```
 
+`--dry-run` runs the full preflight and writes nothing; it will not create a vault on the destination. The exit code and the `success` field track `errors` being empty, so a CI script branching on `.success` sees a partial copy as a failure.
+
 
 ## Observer Events
 
@@ -496,9 +602,26 @@ interface VaultCopyResult {
     errors: Array<{ key: string; error: string }>;
 }
 
+interface PendingVaultUser {
+    identityHash: string;   // stable handle propagation targets
+    publicKey: string;      // X25519 key the vault key is sealed to
+    name: string;
+    email: string;
+}
+
+interface FailedVaultPropagation {
+    identityHash: string;
+    email: string;
+    error: string;
+}
+
 interface VaultPropagationResult {
     propagatedTo: string[];
     alreadyHadAccess: number;
+
+    // Non-empty means the operation partially succeeded: some teammate
+    // believes they have access and does not. Treat as an error.
+    failed: FailedVaultPropagation[];
 }
 ```
 
@@ -507,7 +630,7 @@ interface VaultPropagationResult {
 
 1. **End-to-end encryption** — Secrets encrypted before transmission, decrypted only in memory
 2. **Zero-knowledge database** — Database sees only ciphertext; no plaintext ever stored
-3. **Forward secrecy per user** — Each user's vault key copy uses unique ephemeral keys
+3. **Per-recipient key separation** — Each user's copy of the vault key is sealed under a fresh ephemeral keypair, so no two stored copies share a wrapping key. This is *not* forward secrecy: the recipient's static private key decrypts their copy forever, so a leaked private key exposes every past and future secret in that vault
 4. **Authenticated encryption** — AES-GCM detects tampering
 5. **No shared secrets in transit** — ECDH derives keys without transmitting them
 
diff --git a/docs/dev/version.md b/docs/dev/version.md
index 0a0dd9ac..08058481 100644
--- a/docs/dev/version.md
+++ b/docs/dev/version.md
@@ -24,10 +24,10 @@ Each layer has its own version number in `CURRENT_VERSIONS`:
 import { CURRENT_VERSIONS } from './core/version'
 
 console.log(CURRENT_VERSIONS)
-// { schema: 1, state: 1, settings: 1 }
+// { schema: 2, state: 3, settings: 1 }
 ```
 
-These are independent of the package version. Bumping `schema` to 2 doesn't require bumping `state` or `settings`.
+These are independent of the package version, and of each other. State has moved three times while settings has not moved at all.
 
 
 ## Quick Start
@@ -38,26 +38,28 @@ import { VersionManager, getVersionManager } from './core/version'
 const version = getVersionManager(process.cwd())
 
 // Check status of all layers
-const status = await version.check(db, state, settings)
+const status = await version.check(db, 'postgres', state, settings)
 console.log('Schema needs migration:', status.schema.needsMigration)
 console.log('State needs migration:', status.state.needsMigration)
 console.log('Settings needs migration:', status.settings.needsMigration)
 
 // Migrate everything at once
-const result = await version.ensureCompatible(db, state, settings, '1.0.0')
+const result = await version.ensureCompatible(db, 'postgres', state, settings)
 // Schema is migrated in-place (database)
 // State and settings are returned as new objects
 const migratedState = result.state
 const migratedSettings = result.settings
 ```
 
+Every `VersionManager` method that touches the database takes the dialect as its second argument—the schema layer needs it to know whether the tracking tables live in a `noorm` schema or under `__noorm_*__` prefixes. The CLI version is not a parameter: it is read from `getCurrentVersion()` when the version record is written.
+
 
 ## Version Status
 
 Check versions without modifying anything:
 
 ```typescript
-const status = await version.check(db, state, settings)
+const status = await version.check(db, dialect, state, settings)
 
 // Each layer has the same structure
 interface LayerVersionStatus {
@@ -72,10 +74,10 @@ Helper methods for common checks:
 
 ```typescript
 // Any layer need upgrading?
-const needsUpgrade = await version.needsMigration(db, state, settings)
+const needsUpgrade = await version.needsMigration(db, dialect, state, settings)
 
 // Any layer newer than CLI supports?
-const tooNew = await version.hasNewerVersion(db, state, settings)
+const tooNew = await version.hasNewerVersion(db, dialect, state, settings)
 ```
 
 
@@ -84,21 +86,24 @@ const tooNew = await version.hasNewerVersion(db, state, settings)
 When storage is newer than the CLI supports, migration throws `VersionMismatchError`:
 
 ```typescript
+import { attempt } from '@logosdx/utils'
+
 import { VersionMismatchError } from './core/version'
 
-try {
-    await version.ensureCompatible(db, state, settings, cliVersion)
-}
-catch (err) {
-    if (err instanceof VersionMismatchError) {
-        console.error(`${err.layer} version ${err.current} is newer than CLI supports (${err.expected})`)
-        console.error('Please upgrade noorm')
-        process.exit(1)
-    }
-    throw err
+const [, err] = await attempt(() => version.ensureCompatible(db, dialect, state, settings))
+
+if (err instanceof VersionMismatchError) {
+
+    console.error(`${err.layer} version ${err.current} is newer than CLI supports (${err.expected})`)
+    console.error('Please upgrade noorm')
+    process.exit(1)
 }
+
+if (err) throw err
 ```
 
+`MigrationError` is the other error these calls throw—it carries `layer`, `version`, and the underlying `cause`.
+
 This protects against data corruption when running an old CLI against newer data.
 
 
@@ -108,47 +113,70 @@ Schema migrations use Kysely's dialect-agnostic schema builder. Never write raw
 
 Create a new migration in `src/core/version/schema/migrations/`:
 
+`up` and `down` both receive the dialect, and they need it: since v2 the tracking tables live in a `noorm` schema on PostgreSQL and SQL Server, so neither the table name nor the schema is the same everywhere.
+
 ```typescript
-// src/core/version/schema/migrations/v2.ts
+// src/core/version/schema/migrations/v3.ts
 import type { Kysely } from 'kysely'
+
 import type { SchemaMigration } from '../../types.js'
+import type { Dialect } from '../../../connection/types.js'
+import { getNoormTables } from '../../../shared/tables.js'
 
-export const v2: SchemaMigration = {
-    version: 2,
+/**
+ * Resolve the schema builder for wherever this dialect keeps its tables.
+ */
+function noormSchema(db: Kysely<unknown>, dialect: Dialect) {
+
+    return dialect === 'postgres' || dialect === 'mssql'
+        ? db.withSchema('noorm').schema
+        : db.schema;
+}
+
+export const v3: SchemaMigration = {
+    version: 3,
     description: 'Add tags column to change table',
 
-    async up(db: Kysely<unknown>): Promise<void> {
-        await db.schema
-            .alterTable('__noorm_change__')
+    async up(db: Kysely<unknown>, dialect: Dialect): Promise<void> {
+        const tables = getNoormTables(dialect);
+
+        await noormSchema(db, dialect)
+            .alterTable(tables.change)
             .addColumn('tags', 'varchar(500)', col => col.notNull().defaultTo(''))
             .execute()
     },
 
-    async down(db: Kysely<unknown>): Promise<void> {
-        await db.schema
-            .alterTable('__noorm_change__')
+    async down(db: Kysely<unknown>, dialect: Dialect): Promise<void> {
+        const tables = getNoormTables(dialect);
+
+        await noormSchema(db, dialect)
+            .alterTable(tables.change)
             .dropColumn('tags')
             .execute()
     }
 }
 ```
 
+Hardcoding `__noorm_change__` here would appear to work, because the migration runs without error on MySQL and SQLite. On PostgreSQL and SQL Server it targets a table that no longer exists at that name, and you find out later.
+
 Then register it and bump the version:
 
 ```typescript
 // src/core/version/schema/index.ts
-import { v2 } from './migrations/v2.js'
+import { v3 } from './migrations/v3.js'
 
-const MIGRATIONS: SchemaMigration[] = [v1, v2]
+const MIGRATIONS: SchemaMigration[] = [v1, v2, v3]
 
 // src/core/version/types.ts
 export const CURRENT_VERSIONS = Object.freeze({
-    schema: 2,  // Bumped from 1
-    state: 1,
+    schema: 3,  // Bumped from 2
+    state: 3,
     settings: 1,
 })
 ```
 
+Only the layer you touched moves. The other two keep whatever they were at.
+
 
 ### Schema Migration Guidelines
 
@@ -159,13 +187,13 @@ export const CURRENT_VERSIONS = Object.freeze({
 5. **Create indexes separately** - Use `createIndex()` after table creation.
 
 ```typescript
-// Good: Dialect-agnostic column addition
-await db.schema
-    .alterTable('__noorm_change__')
+// Good: dialect-agnostic column addition, dialect-resolved table name
+await noormSchema(db, dialect)
+    .alterTable(getNoormTables(dialect).change)
     .addColumn('metadata', 'text', col => col.notNull().defaultTo('{}'))
     .execute()
 
-// Bad: Raw SQL for specific dialect
+// Bad: raw SQL for one dialect, and a table name that is wrong on two others
 await sql`ALTER TABLE __noorm_change__ ADD COLUMN metadata JSONB DEFAULT '{}'`.execute(db)
 ```
 
@@ -177,11 +205,11 @@ State migrations transform the decrypted JSON object. They run synchronously and
 Create a new migration in `src/core/version/state/migrations/`:
 
 ```typescript
-// src/core/version/state/migrations/v2.ts
+// src/core/version/state/migrations/v4.ts
 import type { StateMigration } from '../../types.js'
 
-export const v2: StateMigration = {
-    version: 2,
+export const v4: StateMigration = {
+    version: 4,
     description: 'Add lastUsed timestamp to configs',
 
     up(state: Record<string, unknown>): Record<string, unknown> {
@@ -198,7 +226,7 @@ export const v2: StateMigration = {
 
         return {
             ...state,
-            schemaVersion: 2,
+            schemaVersion: 4,
             configs: updatedConfigs,
         }
     },
@@ -215,7 +243,7 @@ export const v2: StateMigration = {
 
         return {
             ...state,
-            schemaVersion: 1,
+            schemaVersion: 3,
             configs: updatedConfigs,
         }
     }
@@ -226,18 +254,20 @@ Register and bump:
 
 ```typescript
 // src/core/version/state/index.ts
-import { v2 } from './migrations/v2.js'
+import { v4 } from './migrations/v4.js'
 
-const MIGRATIONS: StateMigration[] = [v1, v2]
+const MIGRATIONS: StateMigration[] = [v1, v2, v3, v4]
 
 // src/core/version/types.ts
 export const CURRENT_VERSIONS = Object.freeze({
-    schema: 1,
-    state: 2,  // Bumped from 1
+    schema: 2,
+    state: 4,  // Bumped from 3
     settings: 1,
 })
 ```
 
+`migrateState` sets `schemaVersion` to `CURRENT_VERSIONS.state` after the last migration runs, so a migration that forgets to set it still ends up correct—but set it anyway, so a partial run is still coherent.
+
 
 ### State Migration Guidelines
 
@@ -311,31 +341,38 @@ Same as state migrations:
 4. **Make idempotent** - Safe to run multiple times.
 
 
-## Table Name Constants
+## Referring to Tracking Tables
+
+Never hardcode a tracking table name, and do not reach for `NOORM_TABLES` either. That constant is deprecated: it only ever returns the prefixed names, so a query built from it targets a table that does not exist on PostgreSQL or SQL Server, where migration v2 moved everything into a `noorm` schema.
 
-Use `NOORM_TABLES` instead of hardcoding table names:
+Two helpers replace it, and they are used together.
 
 ```typescript
-import { NOORM_TABLES } from './core/version'
-
-console.log(NOORM_TABLES)
-// {
-//     version: '__noorm_version__',
-//     change: '__noorm_change__',
-//     executions: '__noorm_executions__',
-//     lock: '__noorm_lock__',
-//     identities: '__noorm_identities__',
-// }
-
-// Use in queries
-await db.selectFrom(NOORM_TABLES.version).selectAll().execute()
-await db.selectFrom(NOORM_TABLES.change).where('status', '=', 'success').execute()
+import { getNoormTables, noormDb } from './core/shared/tables'
+
+const tables = getNoormTables(dialect);   // the right names for this dialect
+const ndb = noormDb(db, dialect);         // the right schema for this dialect
+
+await ndb.selectFrom(tables.change).selectAll().execute();
 ```
 
+`getNoormTables(dialect)` returns clean names (`change`, `executions`, `lock`) on PostgreSQL and SQL Server, and the `__noorm_*__` prefixed names on MySQL and SQLite.
+
+`noormDb(db, dialect)` wraps the Kysely instance in `withSchema('noorm')` on PostgreSQL and SQL Server, and returns it untouched on MySQL and SQLite.
+
+Neither one is sufficient alone. The names without the schema wrapper resolve against the default schema; the wrapper without the right names looks for `noorm.__noorm_change__`. Take both from the dialect and the same code works everywhere.
+
+```typescript
+// pg / mssql  → SELECT * FROM "noorm"."change"
+// mysql / sqlite → SELECT * FROM `__noorm_change__`
+```
+
+The `NoormDatabase` type is the intersection of both key sets, so either name typechecks.
+
 
 ## Version Record Tracking
 
-The `__noorm_version__` table tracks all three version numbers—not just schema, but also state and settings:
+The version table (`__noorm_version__` on MySQL/SQLite, `noorm.version` on PostgreSQL/SQL Server) tracks all three version numbers—not just schema, but also state and settings:
 
 | Column | Description |
 |--------|-------------|
@@ -352,17 +389,20 @@ This provides a central record in the database of what versions are in use.
 import { getLatestVersionRecord, updateVersionRecord } from './core/version'
 
 // Get current versions from database
-const record = await getLatestVersionRecord(db)
-// { stateVersion: 1, settingsVersion: 1 }
+const record = await getLatestVersionRecord(db, dialect)
+// { stateVersion: 3, settingsVersion: 1 } — or null if no tracking tables
 
 // Update after state/settings migration
-await updateVersionRecord(db, {
-    cliVersion: '1.1.0',
-    stateVersion: 2,
-    settingsVersion: 1,
+await updateVersionRecord(db, dialect, {
+    stateVersion: CURRENT_VERSIONS.state,
+    settingsVersion: CURRENT_VERSIONS.settings,
 })
 ```
 
+`VersionRecordOptions` carries only `stateVersion` and `settingsVersion`, both optional and both defaulting to `CURRENT_VERSIONS`. `cli_version` and `noorm_version` are not callers' to set—the former comes from `getCurrentVersion()`, the latter from `CURRENT_VERSIONS.schema`.
+
+Both reads (`getLatestVersionRecord`, `getSchemaVersion`, `tablesExist`) are two-step: they try the legacy `__noorm_version__` location first, then the schema-qualified `noorm.version` on PostgreSQL and SQL Server. That is what lets a pre-v2 database be recognized before the v2 migration has moved anything.
+
 
 ## Layer-Specific Functions
 
@@ -401,37 +441,38 @@ import {
 
 ### Schema Functions
 
+Every schema function takes the dialect as its second argument.
+
 ```typescript
 // Check if tracking tables exist
-const exists = await tablesExist(db)
+const exists = await tablesExist(db, dialect)
 
 // Get current schema version (0 if no tables)
-const version = await getSchemaVersion(db)
+const version = await getSchemaVersion(db, dialect)
 
 // Check status
-const status = await checkSchemaVersion(db)
-// { current: 0, expected: 1, needsMigration: true, isNewer: false }
+const status = await checkSchemaVersion(db, dialect)
+// { current: 0, expected: 2, needsMigration: true, isNewer: false }
 
 // Bootstrap from scratch (creates tables + version record)
-await bootstrapSchema(db, '1.0.0')
+await bootstrapSchema(db, dialect)
 
 // Bootstrap with specific state/settings versions
-await bootstrapSchema(db, '1.0.0', { stateVersion: 2, settingsVersion: 1 })
+await bootstrapSchema(db, dialect, { stateVersion: 3, settingsVersion: 1 })
 
 // Migrate existing schema
-await migrateSchema(db, '1.0.0')
+await migrateSchema(db, dialect)
 
-// Ensure at current version (migrates if needed)
-await ensureSchemaVersion(db, '1.0.0')
+// Ensure at current version (migrates if needed) — thin alias for migrateSchema
+await ensureSchemaVersion(db, dialect)
 
 // Get latest version record (state/settings versions)
-const record = await getLatestVersionRecord(db)
-// { stateVersion: 1, settingsVersion: 1 } or null
+const record = await getLatestVersionRecord(db, dialect)
+// { stateVersion: 3, settingsVersion: 1 } or null
 
 // Update version record after state/settings migration
-await updateVersionRecord(db, {
-    cliVersion: '1.1.0',
-    stateVersion: 2,
+await updateVersionRecord(db, dialect, {
+    stateVersion: 3,
     settingsVersion: 1,
 })
 ```
@@ -454,7 +495,8 @@ if (needsStateMigration(state)) {
 
 // Create fresh versioned state
 const fresh = createEmptyVersionedState()
-// { schemaVersion: 1, identity: null, knownUsers: {}, ... }
+// { schemaVersion: 3, knownUsers: {}, activeConfig: null, configs: {}, ... }
+// Runs every migration against {}, so it always lands on CURRENT_VERSIONS.state
 
 // Ensure at current version
 const current = ensureStateVersion(state)
@@ -549,13 +591,18 @@ import type {
     NewNoormLock,
     NewNoormIdentity,
 } from './core/version'
+import { getNoormTables, noormDb } from './core/shared/tables'
 
 // Use with Kysely
 const db = new Kysely<NoormDatabase>({ dialect })
 
+// Resolve names and schema from the dialect — see "Referring to Tracking Tables"
+const tables = getNoormTables(dialect)
+const ndb = noormDb(db, dialect)
+
 // Type-safe queries
-const changes = await db
-    .selectFrom('__noorm_change__')
+const changes = await ndb
+    .selectFrom(tables.change)
     .selectAll()
     .where('status', '=', 'success')
     .execute()
@@ -567,9 +614,11 @@ const newChange: NewNoormChange = {
     direction: 'change',
     status: 'pending',
 }
-await db.insertInto('__noorm_change__').values(newChange).execute()
+await ndb.insertInto(tables.change).values(newChange).execute()
 ```
 
+The vault table's types (`NoormVaultTable`, `NoormVault`, `NewNoormVault`) are not re-exported from `./core/version`—import them from `./core/shared` directly.
+
 
 ## Singleton Pattern
 
@@ -588,57 +637,34 @@ beforeEach(() => {
 ```
 
 
-## Integration Example
+## Integration
+
+`VersionManager.ensureCompatible` is the all-three-layers entry point, but nothing in the CLI calls it. The layers are migrated where each one is loaded, which means no caller has to hold all three at once:
 
-Typical initialization flow:
+| Layer | Migrated by | Where |
+|-------|-------------|-------|
+| state | `migrateState` (schema-version), then the package-semver migration | `StateManager.load()` |
+| settings | `migrateSettings` | Settings load path |
+| schema | `ensureSchemaVersion(db, dialect)` | After connect, in the CLI/TUI bootstrap |
+
+Order matters inside `StateManager.load()`: the schema-version migrations run **first**, on the raw record. The package-semver migration only knows `State`'s own top-level fields and would silently drop anything schema-version-owned—including `schemaVersion` itself—if it ran first.
+
+The schema step is what the CLI does after a connection is established:
 
 ```typescript
-import { getVersionManager, VersionMismatchError } from './core/version'
-import { getStateManager } from './core/state'
-import { getSettingsManager } from './core/settings'
-import { createConnection } from './core/connection'
-
-async function initialize(projectRoot: string): Promise<void> {
-
-    // Load current state and settings
-    const stateManager = getStateManager(projectRoot)
-    const settingsManager = getSettingsManager(projectRoot)
-
-    await stateManager.load()
-    await settingsManager.load()
-
-    // Connect to database
-    const config = stateManager.getActiveConfig()
-    const db = await createConnection(config)
-
-    // Check and migrate versions
-    const version = getVersionManager(projectRoot)
-
-    try {
-        const result = await version.ensureCompatible(
-            db,
-            stateManager.getRawState(),
-            settingsManager.getRawSettings(),
-            getPackageVersion()
-        )
-
-        // Save migrated state if changed
-        if (result.state !== stateManager.getRawState()) {
-            await stateManager.saveRawState(result.state)
-        }
+import { attempt } from '@logosdx/utils'
 
-        // Save migrated settings if changed
-        if (result.settings !== settingsManager.getRawSettings()) {
-            await settingsManager.saveRawSettings(result.settings)
-        }
-    }
-    catch (err) {
-        if (err instanceof VersionMismatchError) {
-            console.error('Your data was created by a newer version of noorm.')
-            console.error(`Please upgrade: npm install -g @noormdev/cli`)
-            process.exit(1)
-        }
-        throw err
-    }
+import { ensureSchemaVersion } from './core/version'
+
+const [, schemaError] = await attempt(() => ensureSchemaVersion(ctx.kysely, ctx.dialect))
+
+if (schemaError) {
+
+    outputError(args, `Failed to initialize database schema: ${schemaError.message}`, logger)
+    await attempt(() => ctx.disconnect())
+
+    return [null, schemaError]
 }
 ```
+
+`ensureSchemaVersion` covers the fresh-install case too: `migrateSchema` sees version 0, finds no tables, and bootstraps from scratch. If tables exist but the version record is missing—an interrupted migration—it assumes v1 and runs v2 onward, which is safe because v2 is idempotent.
diff --git a/docs/getting-started/building-your-sdk.md b/docs/getting-started/building-your-sdk.md
index e3aba39f..147aa04e 100644
--- a/docs/getting-started/building-your-sdk.md
+++ b/docs/getting-started/building-your-sdk.md
@@ -336,6 +336,7 @@ export interface ClientOptions {
     config?: string;
     requireTest?: boolean;
     projectRoot?: string;
+    yes?: boolean;
 }
 
 export class Client {
@@ -399,6 +400,7 @@ export async function createClient(options: ClientOptions = {}): Promise<Client>
         config: options.config,
         requireTest: options.requireTest,
         projectRoot: options.projectRoot,
+        yes: options.yes,
     });
 
     return new Client(ctx);
@@ -457,7 +459,10 @@ export interface TestClientOptions {
 /**
  * Create a test database client.
  *
- * Uses requireTest: true to prevent accidentally running against production.
+ * requireTest: true refuses any config that isn't marked as a test database.
+ * yes: true pre-confirms the operations noorm would otherwise stop on.
+ * db:truncate needs confirmation even on an admin config, so without it
+ * every truncate() throws ProtectedConfigError.
  *
  * @example
  * const db = await createTestClient();
@@ -471,6 +476,7 @@ export async function createTestClient(
     return createClient({
         config: 'test',
         requireTest: true,
+        yes: true,
         projectRoot: options.projectRoot,
     });
 
@@ -592,17 +598,19 @@ describe('User Queries', () => {
 
 ## Step 9: Configure Test Database
 
-The SDK uses noorm configs. You'll need a `test` config that points to your test database. Add one via noorm TUI wherever your noorm project lives:
+The SDK uses noorm configs. You'll need a `test` config that points to your test database. Add one via the noorm TUI wherever your noorm project lives:
 
 ```bash
-noorm
+noorm ui
 ```
 
 Press `c` for config, `a` to add:
 
-- **Name**: `test`
+- **Config Name**: `test`
 - **Database**: `my_project_test`
-- **Is Test Database**: Yes
+- **Test Database (skipped in production builds)**: checked
+
+The checkbox is what `requireTest: true` reads. A context created with `requireTest: true` against a config without it throws `RequireTestError` before it ever connects.
 
 
 ## Using Your SDK
@@ -710,15 +718,32 @@ jobs:
                   cache: 'pnpm'
 
             - run: pnpm install
-            - run: pnpm --filter @my-project/db test
+
+            # createTestClient asks for a stored config named `test`, and a
+            # fresh runner has no .noorm/state/state.enc. `ci init` writes one
+            # from the env vars and marks the config active and isTest.
+            # -c runs it in packages/db, which is where vitest's cwd will be,
+            # and createContext resolves state against cwd.
+            - run: npx noorm -c packages/db ci init --name test
               env:
+                  NOORM_IDENTITY_PRIVATE_KEY: ${{ secrets.NOORM_CI_KEY }}
+                  NOORM_IDENTITY_NAME: "GitHub CI"
+                  NOORM_IDENTITY_EMAIL: "ci@example.com"
                   NOORM_CONNECTION_DIALECT: postgres
                   NOORM_CONNECTION_HOST: localhost
                   NOORM_CONNECTION_DATABASE: test
                   NOORM_CONNECTION_USER: postgres
                   NOORM_CONNECTION_PASSWORD: postgres
+
+            - run: pnpm --filter @my-project/db test
+              env:
+                  NOORM_IDENTITY_PRIVATE_KEY: ${{ secrets.NOORM_CI_KEY }}
+                  NOORM_IDENTITY_NAME: "GitHub CI"
+                  NOORM_IDENTITY_EMAIL: "ci@example.com"
 ```
 
+Generate `NOORM_CI_KEY` once with `noorm ci identity new --name "GitHub CI" --email ci@example.com`, which prints the env block to stdout, then paste it into your provider's secret store. If your templates read vault secrets, use `noorm ci identity enroll` instead so the key also gets vault access. See [CI/CD](/guide/automation/ci) for the full walkthrough.
+
 
 ## Final Structure
 
diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md
index e00c5bee..8f43ec77 100644
--- a/docs/getting-started/concepts.md
+++ b/docs/getting-started/concepts.md
@@ -211,18 +211,20 @@ noorm config use staging
 
 Or specify per-command:
 ```bash
-noorm -c prod run build
+noorm run build --config prod
 ```
 
+`--config` is a per-subcommand flag, so it goes *after* the subcommand. Before the subcommand, `-c` means `--cwd` (the only root-level flag), so `noorm -c prod run build` runs the build in a directory named `prod` instead.
+
 
 ## Access Roles
 
 Every config declares an access role — `viewer`, `operator`, or `admin` — separately for two **channels**: `user` (you, at the CLI or TUI) and `agent` (an AI agent, whether it reaches noorm over MCP or by running the CLI). This is how you prevent accidental destructive operations:
 
 - `viewer` - Read-only. `db teardown`, writes, and changes are all blocked.
-- `operator` - Reads and writes are fine; `db teardown` and applying changes require typing a confirmation phrase.
-- `admin` - No friction. Everything is allowed, nothing prompts.
-- Accidental `DROP TABLE` via raw SQL - Still executes if the role allows SQL writes/DDL (be careful!)
+- `operator` - Reads and writes are fine; builds, changes, and `db create` require typing a confirmation phrase. Raw DDL, `db teardown`, and `db drop` are denied outright.
+- `admin` - Builds and changes run without prompting. The operations that cannot be undone still ask: `db drop`, `db teardown`, `db truncate`, `change rm`, `config` edits, `vault propagate`, and `lock force`.
+- Accidental `DROP TABLE` via raw SQL - Still executes if the role allows SQL DDL, which only `admin` does (be careful!)
 
 Roles are a safety net, not a security boundary. They catch mistakes like running teardown against the wrong database — they won't stop a determined user or malicious script.
 
@@ -246,8 +248,10 @@ INSERT INTO app_config (key, value) VALUES
 
 ```bash
 # Set a secret for the current config
-noorm secret set AWS_ACCESS_KEY
-noorm secret set AWS_SECRET_KEY
+noorm secret set AWS_ACCESS_KEY "AKIAEXAMPLE"
+
+# Or pipe the value in so it never reaches the process table or shell history
+printf %s "$AWS_SECRET_KEY" | noorm secret set AWS_SECRET_KEY --stdin
 ```
 
 When you rebuild your database, your credentials are always there—but never exposed in your SQL files or version control.
@@ -257,7 +261,7 @@ Secrets are **config-scoped**. Each config has its own set of secrets (dev AWS v
 
 ## State and Identity
 
-Your **identity** lives in `~/.noorm/identity.json` along with your public and private keys. These are machine-local and never shared.
+Your **identity** lives in `~/.noorm/`, split across three files: `identity.key` (private key, owner-readable only), `identity.pub` (public key), and `identity.json` (metadata such as name, email, and machine). These are machine-local, and the private key is never shared.
 
 Your **state** lives in `.noorm/state/state.enc` and contains:
 
@@ -294,9 +298,11 @@ build:
 
 stages:
   prod:
-    protected: true
+    defaults:
+      protected: true
     secrets:
       - key: AWS_SECRET_KEY
+        type: password
         required: true
 ```
 
@@ -310,19 +316,24 @@ A **stage** is a template for configs. When you create a config and assign it to
 ```yaml
 stages:
   development:
-    dialect: sqlite
-    isTest: false
+    defaults:
+      dialect: sqlite
+      isTest: false
 
   production:
-    dialect: postgres
-    protected: true
+    defaults:
+      dialect: postgres
+      protected: true
     secrets:
       - key: AWS_SECRET_KEY
+        type: password
         required: true
 ```
 
 Now when you create a config with stage `production`, its resolved access is capped to at most `operator`/`viewer` (it can be stricter, never looser), and it requires an `AWS_SECRET_KEY` secret.
 
+Connection values go under `defaults`. Required secrets go under `secrets`, and each entry needs a `type` (`string`, `password`, `api_key`, or `connection_string`). Settings fail to load without it.
+
 
 ## SQL Files vs Changes
 
@@ -332,9 +343,9 @@ Now when you create a config with stage `production`, its resolved access is cap
 | Location | `sql/` | `changes/` |
 | When to run | Fresh database, tests | Existing database |
 | Rollback | No | Yes, with revert scripts |
-| Order | Settings-defined, then alphabetical | By date prefix |
+| Order | Alphanumeric by full path | By date prefix |
 
-**SQL files** are your source of truth. They define what your schema looks like today. Execution order is first determined by folder order in your settings, then alphabetically within each folder.
+**SQL files** are your source of truth. They define what your schema looks like today. Execution order is alphanumeric by full path. `build.include` picks which folders take part; it does not reorder them, so the numeric prefixes are what control the sequence.
 
 **Changes** are your changelog. They document how to get an existing database to match your SQL files.
 
diff --git a/docs/getting-started/first-build.md b/docs/getting-started/first-build.md
index cc831e68..e882cb9c 100644
--- a/docs/getting-started/first-build.md
+++ b/docs/getting-started/first-build.md
@@ -27,14 +27,15 @@ That is the whole loop: `run build` applies the SQL files, `change ff` walks an
 ```bash
 mkdir noorm-tutorial
 cd noorm-tutorial
-noorm ui
+noorm init
 ```
 
-Launching `noorm ui` in an empty directory kicks off the init wizard — it sets up your identity, creates the project scaffolding, and optionally walks you through adding a first config. When it finishes, you'll have this layout:
+`noorm init` sets up your identity (or reuses the one already in `~/.noorm/`) and creates the project scaffolding. When it finishes, you'll have this layout:
 
 ```
 noorm-tutorial/
 ├── .noorm/
+│   ├── .gitignore             # ignores state/
 │   ├── settings.yml           # Project settings (commit this)
 │   └── state/
 │       └── state.enc          # Encrypted state (don't commit)
@@ -42,6 +43,8 @@ noorm-tutorial/
 └── changes/                   # Versioned changes go here
 ```
 
+Configs are added separately, from the TUI. That's the next step.
+
 
 ## Step 2: Add a Database Config
 
@@ -60,8 +63,11 @@ Press `c` for config, then `a` to add a new config. Fill out the form:
 - **Database**: `noorm_dev`
 - **Username**: `postgres`
 - **Password**: your password
+- **User Role (CLI/TUI access)**: leave at `admin`
+- **Agent Role (MCP/CLI access)**: leave at `viewer`
+- **Test Database**: leave unchecked
 
-Leave the SQL Path and Changes Path at their defaults (`./sql` and `./changes`). Submit the form to save your config.
+Submit the form to save your config. SQL and changes paths are not part of a config. They live in `.noorm/settings.yml` under `paths`, and default to `./sql` and `./changes`.
 
 
 ## Step 3: Create the Database
@@ -72,15 +78,16 @@ Back at the home screen, press `d` for Database. You'll see the Database Operati
 Database Operations
 
 Config:      dev
-Connection:  CONNECTED
+Connection:  NOT CREATED
 
 Available Actions
 
-[c] Create - Build database from SQL files
+[c] Create - Create database and tracking tables
 [d] Destroy - Drop all managed objects
 [x] Explore - Browse database schema
 [w] Wipe - Truncate table data (keep schema)
 [t] Teardown - Drop user objects (keep noorm)
+[r] Transfer - Copy data to another database
 ```
 
 Press `c` to create. noorm will create the `noorm_dev` database on your PostgreSQL server and initialize its tracking tables.
@@ -156,9 +163,10 @@ noorm run build
 Output:
 
 ```
-• build:start    Starting schema build (1 files)
-• file:after     Executed sql/01_tables/001_users.sql (12ms)
-• log            Build completed successfully  filesRun=1 filesSkipped=0
+• build:start     Starting schema build (1 files)
+• file:after      Executed sql/01_tables/001_users.sql (12ms)
+• build:complete  Build complete: 1 run, 0 skipped (18ms)
+• log             Build completed  status=success filesRun=1 filesSkipped=0 filesFailed=0 durationMs=18
 ```
 
 Your users table now exists.
@@ -270,14 +278,14 @@ noorm change ff
 Output:
 
 ```
-• change:start   Applying 2024-01-15-add-posts-and-bio
-• file:after     Executed 001_add_bio.sql (8ms)
-• file:after     Executed 01_tables/002_posts.sql (15ms)
-• file:after     Executed 02_views/001_recent_posts.sql (6ms)
-• change:after   Applied 2024-01-15-add-posts-and-bio
-• log            Changes applied successfully  applied=1 skipped=0
+• change:start     Starting change for 2024-01-15-add-posts-and-bio (3 files)
+• change:complete  change 2024-01-15-add-posts-and-bio: success (29ms)
+• log              Fast-forward success  executed=1 skipped=0 failed=0
+• log                2024-01-15-add-posts-and-bio (success)
 ```
 
+Three files, because the `002_schema.txt` manifest expands to the two SQL files it names. Per-file lines are `change:file` events, which sit at debug level. Raise `logging.level` to `verbose` in `.noorm/settings.yml` to see them.
+
 Your dev database now matches your SQL files.
 
 
@@ -300,11 +308,12 @@ noorm run build
 Output:
 
 ```
-• build:start    Starting schema build (3 files)
-• file:after     Executed sql/01_tables/001_users.sql (14ms)
-• file:after     Executed sql/01_tables/002_posts.sql (11ms)
-• file:after     Executed sql/02_views/001_recent_posts.sql (7ms)
-• log            Build completed successfully  filesRun=3 filesSkipped=0
+• build:start     Starting schema build (3 files)
+• file:after      Executed sql/01_tables/001_users.sql (14ms)
+• file:after      Executed sql/01_tables/002_posts.sql (11ms)
+• file:after      Executed sql/02_views/001_recent_posts.sql (7ms)
+• build:complete  Build complete: 3 run, 0 skipped (32ms)
+• log             Build completed  status=success filesRun=3 filesSkipped=0 filesFailed=0 durationMs=32
 ```
 
 The test database has the complete schema from your SQL files. No changes needed—they're only for evolving existing databases.
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 8ef60932..054f0077 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -134,18 +134,20 @@ The single most common mistake — by people and agents alike — is writing `bu
 
 ## Initialize a Project
 
-After installation, launch the TUI in your project root — it detects the missing `.noorm/` directory and walks you through identity setup, project structure, and the first config:
+Run `noorm init` in your project root. It prompts for the identity to create (skipped if you already have one) and scaffolds the project:
 
 ```bash
 cd your-project
-noorm ui
+noorm init
 ```
 
 The init wizard creates:
 
 ```
 your-project/
+├── .gitignore                 # gets a .noorm/state/ entry appended
 ├── .noorm/
+│   ├── .gitignore             # ignores state/
 │   ├── settings.yml           # Project settings (commit this)
 │   └── state/
 │       └── state.enc          # Encrypted state (don't commit)
@@ -155,8 +157,12 @@ your-project/
     └── .gitkeep
 ```
 
+`noorm init` is strictly interactive and exits with an error on a non-TTY unless you pass `--yes` and already have an identity at `~/.noorm/identity.{key,pub,json}`.
+
+Adding the first database config comes next, from the TUI (`noorm ui`, then `c` for config and `a` to add).
+
 ::: warning Git Ignore
-Add `.noorm/state/` to your `.gitignore`. This folder contains encrypted configs and secrets specific to each developer's machine. The `.noorm/settings.yml` should be committed — it's the shared project configuration.
+`noorm init` adds `.noorm/state/` to your `.gitignore` for you. That folder holds encrypted configs and secrets specific to each developer's machine. The `.noorm/settings.yml` should be committed — it's the shared project configuration.
 :::
 
 
diff --git a/docs/guide/automation/ci.md b/docs/guide/automation/ci.md
index 1a68a982..f08ddc33 100644
--- a/docs/guide/automation/ci.md
+++ b/docs/guide/automation/ci.md
@@ -114,9 +114,12 @@ Run this on a machine that already has vault access on the target config:
 noorm ci identity enroll \
     --config prod \
     --name "GitHub CI" \
-    --email ci@example.com
+    --email ci@example.com \
+    --yes
 ```
 
+`--yes` is required, not optional. Enrollment ends in a `vault:propagate` grant, which the matrix marks `confirm` for every role that holds it, and sealing the vault key to a public key cannot be undone. Without `--yes` (or `NOORM_YES=1`) the command prints the identity it was about to grant to and exits 1 so you can check it first.
+
 The command:
 
 1. Mints a new X25519 keypair.
@@ -142,12 +145,13 @@ noorm ci identity enroll \
     --config prod \
     --name "GitHub CI" \
     --email ci@example.com \
-    --public-key <hex-from-ci-identity.json>
+    --public-key <hex-from-ci-identity.json> \
+    --yes
 ```
 
-Only the public half is enrolled. The private key never leaves the first machine.
+Only the public half is enrolled. The private key never leaves the first machine. The public key is 88 hex characters; anything else is rejected before a row is written.
 
-Both commands are **idempotent on identityHash** — re-running just ensures vault access, so you can replay them safely if anything fails partway through.
+`ci identity enroll` is **idempotent on identityHash** — re-running just ensures vault access, so you can replay it safely if anything fails partway through. It refuses outright when a row already exists under that hash carrying a *different* public key, since granting there would seal the vault key to someone else's key.
 
 
 ### Every Job: Runtime Bootstrap
@@ -161,7 +165,7 @@ noorm change ff
 
 `ci init` reads `NOORM_IDENTITY_*` and `NOORM_CONNECTION_*`, writes a fresh `.noorm/state/state.enc`, creates a config (default name `ci`, override via `--name` or `NOORM_CI_CONFIG_NAME`), and marks it active. After it runs, every other `noorm` command in the job works exactly as if a developer had bootstrapped the project manually.
 
-If the env vars are missing, malformed, or `state.enc` already exists (without `--force`), `ci init` exits 1 before doing anything else.
+If the env vars are missing or malformed, `ci init` exits 2 (bad invocation) before doing anything else. If `state.enc` already exists and `--force` was not passed, it exits 1. With `--force` it backs the old file up next to it first, and from an interactive terminal it also demands `--yes`, since overwriting destroys every config and config-scoped secret in the project.
 
 
 ### Loading Per-Job Secrets
@@ -290,9 +294,10 @@ export NOORM_CONNECTION_PASSWORD=$DB_PASSWORD
 
 noorm ci init --name prod
 
-# Prevent concurrent migrations
+# Prevent concurrent migrations. `change ff` releases the lock itself once
+# the last change lands, so the trap tolerates an already-released lock.
 noorm lock acquire
-trap "noorm lock release" EXIT
+trap 'noorm lock release || true' EXIT
 
 noorm change ff
 noorm db explore --json
@@ -310,6 +315,7 @@ noorm db explore --json
 | `NOORM_IDENTITY_NAME` | Prod CI | Display name (e.g. `"GitHub CI"`) |
 | `NOORM_IDENTITY_EMAIL` | Prod CI | Email address |
 | `NOORM_CI_CONFIG_NAME` | Optional | Default config name for `ci init` |
+| `NOORM_YES` | Optional | Truthy value stands in for `--yes` on every command. Truthy is any non-empty value except `0` and `false` |
 | `NOORM_CONNECTION_DIALECT` | Always | `postgres`, `mysql`, `sqlite`, or `mssql` |
 | `NOORM_CONNECTION_HOST` | Dialect-specific | Host |
 | `NOORM_CONNECTION_PORT` | Dialect-specific | Port |
@@ -323,7 +329,7 @@ noorm db explore --json
 | Command | Runs on | Purpose |
 |---|---|---|
 | `noorm ci identity new` | Developer machine | Mint a CI keypair + print env block. No DB contact. |
-| `noorm ci identity enroll` | Developer machine (with vault access) | Enroll a CI identity in a target DB; grant vault access. Idempotent. |
+| `noorm ci identity enroll --yes` | Developer machine (with vault access) | Enroll a CI identity in a target DB; grant vault access. Idempotent. `--yes` required. |
 | `noorm ci init` | CI runner | Bootstrap ephemeral `state.enc` from env; create & activate a config. |
 | `noorm ci secrets --file <path>` | CI runner (after `ci init`) | Batch-load secrets from dotenv into the active config. |
 
@@ -332,9 +338,12 @@ noorm db explore --json
 
 | Code | Meaning |
 |---|---|
-| `0` | Success |
-| `1` | Precondition failure — missing env var, missing state, parse error, total failure |
-| `2` | Partial success (`ci secrets` only) — some keys written, some errored |
+| `0` | Success — everything the caller asked for happened |
+| `1` | Total failure — the operation ran and no unit of work succeeded |
+| `2` | Bad invocation — a missing or malformed flag or env var, or a named target (config, file, change) that does not exist. Nothing was attempted |
+| `3` | Partial — some units of work succeeded and some failed. The target is in a mixed state and re-running is not automatically safe |
+
+These four codes are shared by every noorm command, not just `ci`. `2` and `3` are what let a pipeline tell "you named something that isn't there" (retry is pointless) from "half of it landed" (a human needs to look).
 
 
 ## See Also
diff --git a/docs/guide/automation/mcp.md b/docs/guide/automation/mcp.md
index 0862d57c..7e6fa823 100644
--- a/docs/guide/automation/mcp.md
+++ b/docs/guide/automation/mcp.md
@@ -77,13 +77,15 @@ If you need to configure the server manually (e.g., for a custom agent), add thi
 {
     "mcpServers": {
         "noorm": {
-            "command": "npx",
-            "args": ["noorm", "mcp", "serve"]
+            "command": "noorm",
+            "args": ["mcp", "serve"]
         }
     }
 }
 ```
 
+This is the exact entry `noorm mcp init` writes, so the two routes produce the same server.
+
 The server uses stdio transport — no ports, no HTTP.
 
 
@@ -91,14 +93,13 @@ The server uses stdio transport — no ports, no HTTP.
 
 Once connected, your agent can:
 
-- **Explore schemas** — list tables, columns, foreign keys, indexes
-- **Run SQL** — execute queries and get structured results
-- **Manage configs** — list, switch, and validate connections
-- **Apply changes** — run forward/revert migrations
-- **Build schemas** — execute SQL files
-- **Inspect templates** — see available context before rendering
+- **Explore schemas** — `overview`, `list`, `detail` for tables, columns, foreign keys, indexes
+- **Run SQL** — `sql` executes a query and returns structured results
+- **Manage connections** — `list_configs`, `connect`, `disconnect`, `status`
+- **Apply changes** — `change_run`, `change_ff`, `change_revert`, `change_history`
+- **Build schemas** — `run_build`, `run_file`
 
-Config resolution and identity attribution work the same as the CLI. Access control does not: every command is gated by the config's **`agent` role** before its handler ever runs, and there is no confirmation flow — the agent gets an answer, not a prompt.
+Config resolution and identity attribution work the same as the CLI. Access control does not: every config-scoped command is gated by the config's **`agent` role** before its handler ever runs, and there is no confirmation flow — the agent gets an answer, not a prompt.
 
 
 ## Access Roles
@@ -111,12 +112,12 @@ A config that never declared `access` gets `{ user: 'admin', agent: 'viewer' }`.
 
 | Role | What the agent can do |
 |------|------------------------|
-| `viewer` | Explore schema, run read-only SQL (`SELECT`, `EXPLAIN`, `SHOW`, `DESCRIBE`) |
-| `operator` | Everything `viewer` can, plus SQL writes (`INSERT`/`UPDATE`/`DELETE`) — destructive commands (`change_run`, `run_build`, etc.) are still out of reach |
-| `admin` | Full access: writes, DDL, changes, builds — frictionless, no confirmation |
+| `viewer` | Explore schema, run read-only SQL (`SELECT`, `SHOW`, `DESCRIBE`) |
+| `operator` | Everything `viewer` can, plus SQL writes (`INSERT`/`UPDATE`/`DELETE`) — DDL and destructive commands (`change_run`, `run_build`, etc.) are still out of reach |
+| `admin` | Writes, DDL, changes, builds, all frictionless. Permissions the matrix marks `confirm` even for `admin` (`db:teardown`, `db:destroy`, `config:write`) still deny on this channel |
 | `false` | Invisible — the config does not exist on this channel |
 
-Raw SQL is classified by what the statement actually does (`sql:read` / `sql:write` / `sql:ddl`), not by which command the agent called — an agent with `agent: viewer` gets a `SELECT` through but a same-shaped `INSERT` denied.
+Raw SQL is classified by what the statement actually does (`sql:read` / `sql:write` / `sql:ddl`), not by which command the agent called — an agent with `agent: viewer` gets a `SELECT` through but a same-shaped `INSERT` denied. `EXPLAIN` takes the class of the statement it wraps, because `EXPLAIN ANALYZE` runs that statement: `EXPLAIN SELECT` is a read, `EXPLAIN DELETE` is a write.
 
 The matrix's `confirm` cells never prompt on this channel — they resolve straight to **deny**. An agent typing its own confirmation phrase would be theater, not a safeguard, and on the CLI it would need only `--yes`. If an agent legitimately needs to run changes on a database, give that config `agent: 'admin'` — reserve it for configs where that's an acceptable risk (a disposable dev database, say), not production.
 
@@ -131,7 +132,7 @@ access:
 
 ## Invisible Configs
 
-Set `access.agent: false` to hide a config from agents entirely — over MCP it never appears in `list_configs`, and `connect`/`getContext` fail with the same error an unknown config name would produce. `noorm config list` filters it the same way when an agent runs it. An agent enumerating configs cannot tell the difference between "doesn't exist" and "exists but is off-limits."
+Set `access.agent: false` to hide a config from agents entirely — over MCP it never appears in `list_configs` or `status`, and `connect` fails with the same error an unknown config name would produce. `noorm config list` filters it the same way when an agent runs it. An agent enumerating configs cannot tell the difference between "doesn't exist" and "exists but is off-limits."
 
 
 ## Security
diff --git a/docs/guide/automation/non-interactive.md b/docs/guide/automation/non-interactive.md
index 5394a302..9d5b0743 100644
--- a/docs/guide/automation/non-interactive.md
+++ b/docs/guide/automation/non-interactive.md
@@ -61,8 +61,9 @@ errors fast and points at the headless alternative.
 | `noorm settings edit` | Edit `settings.yml` directly; run `noorm settings build` to validate. |
 | `noorm settings secret` | Edit the `secrets:` section of `settings.yml` directly. For values, use `noorm secret set <key> <value>`. |
 
-These commands exit 1 with the redirect message on stderr. Same exit
-code as the TTY refusal, so existing CI checks don't change behavior.
+These commands exit 2 (bad invocation) with the redirect message on
+stderr. Same exit code as their TTY refusal, so a pipeline sees one
+code whichever way it hit the gate.
 
 
 ### Already non-interactive (no `--yes` needed)
@@ -71,7 +72,12 @@ These accept explicit flags and don't gate on a TTY:
 
 - `noorm identity init --name "..." --email "..."` — bootstraps the identity used by `noorm init --yes`.
 - `noorm config import <path>` — wizard-free config setup.
-- `noorm ci init` / `ci secrets` / `ci identity new` / `ci identity enroll` — the dedicated CI bootstrap surface.
+- `noorm ci init` / `ci secrets` / `ci identity new` — the dedicated CI bootstrap surface.
+
+One exception inside that surface: `noorm ci identity enroll` **does** need
+`--yes` (or `NOORM_YES=1`). It ends in a `vault:propagate` grant, which the
+matrix marks `confirm` for every role that holds it, and sealing the vault
+key to a public key cannot be undone.
 
 
 ## CI bootstrap pipeline
@@ -82,7 +88,7 @@ with no prompts:
     #!/usr/bin/env bash
     set -euo pipefail
 
-    # 1. Identity (once per machine; idempotent if files exist + --force).
+    # 1. Identity (once per machine; exits 1 if one already exists).
     noorm identity init \
       --name "$CI_USER" \
       --email "$CI_EMAIL"
@@ -102,6 +108,17 @@ with no prompts:
     noorm run build
     noorm change ff
 
+Step 1 is not idempotent, and under `set -e` it aborts the script if an
+identity already exists. Replacing one takes `--force --yes` together,
+mints a fresh keypair, and leaves any state encrypted under the old key
+unreadable. Guard it instead of passing `--force` blind:
+
+    [ -f ~/.noorm/identity.key ] || noorm identity init \
+      --name "$CI_USER" --email "$CI_EMAIL"
+
+The raw `--yes` flag is required for a replacement; an ambient
+`NOORM_YES` deliberately does not satisfy it.
+
 If you need a stored config (rather than env-only), use `noorm config
 import <path>` with a pre-built JSON file. See
 [`docs/headless.md`](../../headless.md) for the full env-only matrix.
@@ -112,8 +129,8 @@ import <path>` with a pre-built JSON file. See
 `--yes` covers prompts. It does NOT relax safety gates that exist for
 destructive operations:
 
-- `noorm db drop`, `noorm db reset`, `noorm db teardown` still require `--yes` *or* `--force` per their own contracts. `NOORM_YES=1` does count toward those gates.
-- Every destructive command is also gated by the config's access role (`viewer`/`operator`/`admin` — see [Access Roles](../../headless.md#access-roles)). `--yes`/`NOORM_YES=1` only skips an `operator` confirmation prompt; it cannot open a `deny` cell. A `viewer`-role config still refuses `db teardown` no matter how many flags you pass.
+- `noorm db drop`, `noorm db reset`, `noorm db teardown` still require `--yes` per their own contracts. `NOORM_YES=1` does count toward those gates.
+- Every destructive command is also gated by the config's access role (`viewer`/`operator`/`admin` — see [Access Roles](../../headless.md#access-roles)). `--yes`/`NOORM_YES=1` only satisfies a `confirm` cell; it cannot open a `deny` cell. A `viewer`- or `operator`-role config still refuses `db teardown` no matter how many flags you pass.
 - Vault and identity operations that need a private key still need the key — either on disk at `~/.noorm/identity.key` or in `$NOORM_IDENTITY_PRIVATE_KEY`.
 
 If a command refuses with a useful error in interactive mode, it refuses
diff --git a/docs/guide/changes/forward-revert.md b/docs/guide/changes/forward-revert.md
index 3474898d..e10837ed 100644
--- a/docs/guide/changes/forward-revert.md
+++ b/docs/guide/changes/forward-revert.md
@@ -21,22 +21,26 @@ noorm change ff
 noorm change ff --json
 ```
 
-Fast-forward is the workhorse for deployments. It finds all unapplied changes, sorts them by date, and executes each one in sequence. If any change fails, execution stops immediately.
+Fast-forward is the workhorse for deployments. It finds every outstanding change (`pending`, `reverted`, or `stale` after a teardown), sorts them by folder name so the `YYYY-MM-DD` prefix puts them in chronological order, and executes each one in sequence. If any change fails, execution stops immediately.
 
 **JSON output:**
 ```json
 {
+    "success": true,
     "status": "success",
-    "applied": 2,
+    "executed": 2,
     "skipped": 0,
     "failed": 0,
+    "durationMs": 77,
     "changes": [
-        {"name": "2024-02-01-add-notifications", "status": "success", "durationMs": 45},
-        {"name": "2024-02-15-user-preferences", "status": "success", "durationMs": 32}
+        {"name": "2024-02-01-add-notifications", "direction": "change", "status": "success", "durationMs": 45},
+        {"name": "2024-02-15-user-preferences", "direction": "change", "status": "success", "durationMs": 32}
     ]
 }
 ```
 
+Each entry in `changes` also carries a `files` array with one record per SQL file: relative path, checksum, status, duration, and the error message when the file failed. If the `changes/` directory is missing, the payload gains a `warnings` array saying so, because an absent directory otherwise looks identical to an up-to-date database.
+
 
 ### Apply a Specific Change
 
@@ -96,7 +100,13 @@ Revert the last N applied changes:
 noorm change rewind 3
 ```
 
-Rewind walks through your applied changes starting with the newest, reverting each one before moving to the next oldest.
+Rewind walks through your applied changes starting with the newest, reverting each one before moving to the next oldest. It considers only changes currently recorded as `success`, and orders them by when they were applied. Changes applied in the same second, which is everything a single `change ff` applies, tie on that timestamp, so the tracking table's row id breaks the tie and preserves true apply order.
+
+Pass a change name instead of a count to rewind back to and including that change:
+
+```bash
+noorm change rewind 2024-02-01-add-notifications
+```
 
 
 ## What Happens During Apply
@@ -109,28 +119,30 @@ When you apply a change, noorm:
 
 3. **Checks the database record** - Looks up this change's status to determine if it should run.
 
-4. **Resolves manifest references** - For `.txt` files, replaces file references with actual SQL content from your schema directory.
+4. **Acquires the config lock** - Stops a second operation on the same config from running concurrently. The lock is released when the change finishes, whatever the outcome.
+
+5. **Resolves manifest references** - For `.txt` files, replaces file references with actual SQL content from your schema directory.
 
-5. **Processes templates** - For `.sql.tmpl` files, runs them through the Eta templating engine.
+6. **Processes templates** - For `.sql.tmpl` files, runs them through the Eta templating engine.
 
-6. **Executes SQL in sequence** - Runs each file in order (`001_`, `002_`, etc.) against the database.
+7. **Executes SQL in sequence** - Runs each file in order (`001_`, `002_`, etc.) against the database. A file whose checksum matches a still-standing success from an earlier attempt is skipped, so a retry only re-runs what actually needs re-running.
 
-7. **Records the result** - Stores the execution status, checksum, and timestamp in the tracking table.
+8. **Records the result** - Stores the execution status, checksum, and timestamp in the change tracking tables.
 
-If any file fails, execution stops. The change is marked as `failed`, and subsequent files in that change are not executed.
+If any file fails, execution stops, and the files that were never reached are recorded as skipped. On PostgreSQL the whole change runs inside one transaction, so the failure rolls back the DDL and the history rows together and the change leaves no record at all. On MySQL, SQL Server, and SQLite there is no wrapping transaction: whatever already committed stays committed, and the change is recorded as `failed`.
 
 
 ## What Happens During Revert
 
 Reverting follows a similar process but with key differences:
 
-1. **Verifies the change is applied** - You cannot revert a change that was never applied or has already been reverted.
+1. **Verifies the change can be reverted** - A change recorded as `success` or `failed` can be reverted. One that was never applied, is already `reverted`, or went `stale` after a teardown cannot. `--force` skips this check.
 
 2. **Reads the revert folder** - Loads files from `revert/` instead of `change/`.
 
 3. **Executes in sequence order** - Files run from lowest to highest (`001_`, `002_`, etc.), same as change scripts.
 
-4. **Updates the record** - Marks the change as `reverted` with a timestamp.
+4. **Updates the records** - Writes its own history record with direction `revert`, then flips the original forward record's status to `reverted`. The revert record's timestamp is what surfaces as `revertedAt`.
 
 After reverting, the change returns to a state where it can be applied again. This is the `reverted` status, which noorm treats as "needs to run" during the next fast-forward.
 
@@ -139,7 +151,7 @@ After reverting, the change returns to a state where it can be applied again. Th
 
 Preview what would happen without touching the database:
 
-**TUI:** In any run dialog, enable the dry-run toggle before confirming.
+**TUI:** Press `Shift+D` to turn on dry-run mode. It is a global toggle, so every apply and revert stays a dry run until you press it again.
 
 **Headless:**
 
@@ -147,19 +159,21 @@ Preview what would happen without touching the database:
     noorm change run 2024-02-01-add-notifications --dry-run
     noorm change revert 2024-02-01-add-notifications --dry-run
     noorm change next --dry-run
+    noorm change rewind 3 --dry-run
 
-Dry run writes rendered SQL to a `tmp/` folder so you can inspect exactly what would execute. Templates are processed, manifests are resolved, but no SQL hits the database — `__noorm_change__` and `__noorm_executions__` are left untouched.
+Dry run writes rendered SQL to a `tmp/` folder so you can inspect exactly what would execute. Templates are processed and manifests are resolved, but nothing from your change files runs against the database and nothing is written to the change tracking tables: the dry-run path skips the status lookup, takes no lock, and creates no history record. `ff`, `next`, and `rewind` still read the tracking tables to decide which changes to render.
 
-The CLI marks dry-run output with a clear `(dry-run)` header so log scrapers and operators can distinguish it from a real apply. With `--json`, the result payload includes a `dryRun: true` field:
+In human mode the CLI opens with `Dry run: rendering changes to tmp/ (no DB writes)`, labels the summary line `(dry-run)`, and tags each change `dry-run`, so log scrapers and operators can tell it apart from a real apply. With `--json` those lines are suppressed and the result payload carries a `dryRun: true` field instead (`rewind --json` is the exception and omits it):
 
     $ noorm change ff --dry-run --json
-    Dry run: rendering changes to tmp/ (no DB writes)
     {
+      "success": true,
       "status": "success",
       "executed": 2,
       "skipped": 0,
       "failed": 0,
-      "changes": [ /* ... */ ],
+      "durationMs": 12,
+      "changes": [],
       "dryRun": true
     }
 
@@ -170,13 +184,15 @@ This is essential for production deployments. Always preview before applying.
 
 When a change fails:
 
-1. **Execution stops immediately** - No further files in the change execute.
+1. **Execution stops immediately** - No further files in the change execute. The ones never reached are recorded as `skipped`, with the failing file named as the reason.
 
 2. **Status is recorded as failed** - The change shows `failed` in the list.
 
-3. **Error details are captured** - The specific error message is stored for debugging.
+3. **Error details are captured** - The failing file name and the database's error message are stored on both the change record and that file's record.
+
+4. **Next fast-forward will retry** - Failed changes are outstanding work, so the next `ff` attempt includes them.
 
-4. **Next fast-forward will retry** - Failed changes are automatically included in the next `ff` attempt.
+On PostgreSQL, steps 2 and 3 do not survive the failure. The change runs inside one transaction, DDL and history rows alike, so a failure rolls all of it back and leaves no record behind. You still see the error in the command's output and exit code, and the next `ff` reruns the change because the tracking tables show it as never applied. MySQL, SQL Server, and SQLite have no wrapping transaction and keep the `failed` record.
 
 
 ### Investigating Failures
@@ -188,7 +204,7 @@ When a change fails:
 noorm change history
 ```
 
-The history shows which specific file failed and includes the error message from the database. See [History](/guide/changes/history) for detailed debugging workflows.
+The history shows which specific file failed and includes the error message from the database. On PostgreSQL there is nothing to show, since a failed change rolls its history rows back with the DDL; read the error off the failing command instead. See [History](/guide/changes/history) for detailed debugging workflows.
 
 
 ### Recovering from Failures
diff --git a/docs/guide/changes/history.md b/docs/guide/changes/history.md
index ed1b6b57..9954ebfe 100644
--- a/docs/guide/changes/history.md
+++ b/docs/guide/changes/history.md
@@ -12,7 +12,7 @@ noorm records three types of operations:
 
 | Type | Description | Trigger |
 |------|-------------|---------|
-| **change** | Change execution | `change run`, `change ff`, `change next` |
+| **change** | Change execution | `change run`, `change ff`, `change next`, `change revert`, `change rewind` |
 | **build** | Full schema rebuild | `run build` |
 | **run** | Individual file execution | `run file`, `run directory` |
 
@@ -20,7 +20,7 @@ Each record captures:
 
 - **Name** - Which change, build, or file was executed
 - **Direction** - Forward (`change`) or rollback (`revert`)
-- **Status** - `success`, `failed`, or `skipped`
+- **Status** - `pending` while the operation is in flight, then `success`, `failed`, `reverted`, or `stale`
 - **Who** - The identity that ran it (name and email)
 - **When** - Timestamp of execution
 - **Duration** - How long it took in milliseconds
@@ -60,8 +60,9 @@ Navigate to history from the changes menu. Press `g` from home, then `h` for his
 The summary bar shows totals by type. Color-coded status indicators make it easy to spot failures:
 
 - Green `[OK]` - Success
-- Red `[ERR]` - Failed
-- Yellow `[-]` - Skipped
+- Red `[ERR]` - Anything else
+
+The list only separates success from not-success. The per-file detail view adds a yellow `[-]` for skipped files.
 
 Arrow keys move through the list. The detail panel at the bottom shows who ran the selected operation and how long it took.
 
@@ -111,13 +112,15 @@ For CI/CD pipelines and scripts, use the headless command:
 noorm change history
 ```
 
+Unlike the TUI screen, this command returns change operations only. Builds and file runs live in the same tracking tables but do not appear here.
+
 Output:
 
 ```
 Execution History: 20 records
   2025-01-15-add-verification - success (1/15/2025, 2:30:00 PM)
-  schema-build - success (1/15/2025, 11:00:00 AM)
-  2025-01-14-add-user-roles - success (1/14/2025, 4:15:00 PM)
+  2025-01-14-add-user-roles - reverted (1/14/2025, 4:15:00 PM)
+  2025-01-10-init-schema - success (1/10/2025, 9:05:00 AM)
 ```
 
 With JSON output for parsing:
@@ -127,27 +130,38 @@ noorm change history --json
 ```
 
 ```json
-[
-    {
-        "name": "2025-01-15-add-verification",
-        "status": "success",
-        "direction": "change",
-        "executedAt": "2025-01-15T14:30:00Z",
-        "executedBy": "Alice <alice@example.com>",
-        "durationMs": 1240
-    },
-    {
-        "name": "schema-build",
-        "status": "success",
-        "direction": null,
-        "executedAt": "2025-01-15T11:00:00Z",
-        "executedBy": "CI Pipeline <ci@company.com>",
-        "durationMs": 5830
-    }
-]
+{
+    "success": true,
+    "history": [
+        {
+            "id": 42,
+            "name": "2025-01-15-add-verification",
+            "direction": "change",
+            "status": "success",
+            "executedAt": "2025-01-15T14:30:00.000Z",
+            "executedBy": "Alice <alice@example.com>",
+            "durationMs": 1240,
+            "errorMessage": null,
+            "checksum": "8f4a2b3c9d1e..."
+        },
+        {
+            "id": 41,
+            "name": "2025-01-14-add-user-roles",
+            "direction": "revert",
+            "status": "success",
+            "executedAt": "2025-01-14T16:15:00.000Z",
+            "executedBy": "CI Pipeline <ci@company.com>",
+            "durationMs": 320,
+            "errorMessage": null,
+            "checksum": "3b7c8d2a4f5e..."
+        }
+    ]
+}
 ```
 
-Limit the number of records:
+The `id` is what `noorm change history-detail` and the TUI drill-down use to fetch the per-file records for an operation.
+
+Limit the number of records (default 20):
 
 ```bash
 noorm change history --count 50
@@ -156,7 +170,7 @@ noorm change history --count 50
 
 ## Filtering by Type
 
-The history screen shows all operation types by default. The summary bar helps you understand the distribution:
+The TUI history screen shows all three operation types by default. The summary bar helps you understand the distribution:
 
 ```
 Total: 47   Changes: 32   Builds: 10   Runs: 5
@@ -197,15 +211,15 @@ Identity is captured from git config or explicitly set via `noorm identity`. Thi
 
 ### When It Ran
 
-Timestamps appear in relative format in the TUI:
+Timestamps appear in relative format in the TUI, rendered by day.js `fromNow()`:
 
-- `just now` - Within the last minute
+- `a few seconds ago` - Just happened
 - `2 hours ago` - Recent operations
-- `yesterday` - Previous day
-- `last week` - Within the past week
-- `Jan 15` - Specific date for older records
+- `a day ago` - Previous day
+- `7 days ago` - Within the past week
+- `a month ago` - Older records
 
-The JSON output provides ISO timestamps for precise filtering and analysis.
+Relative time is all the TUI shows, however old the record. The JSON output provides ISO timestamps for precise filtering and analysis.
 
 
 ### How Long It Took
@@ -234,18 +248,18 @@ The detail view breaks down each file:
 |--------|------|---------|
 | Success | `[OK]` | File executed without errors |
 | Failed | `[ERR]` | Execution threw an error |
-| Skipped | `[-]` | File was skipped (unchanged or conditional) |
+| Skipped | `[-]` | Either a prior run already applied this exact file, or an earlier file in the change failed and this one was never reached |
 
 For skipped files, the skip reason explains why:
 
 ```
-[-]  setup.sql     - unchanged since last run
+[-]  setup.sql     - already applied
 ```
 
 
 ## Using History for Debugging
 
-When something goes wrong, history is your first stop.
+When something goes wrong, history is your first stop, with one dialect-specific exception. On PostgreSQL a change runs inside a transaction that covers its history rows as well as its DDL, so a failed change rolls back completely and writes nothing to history. Read the error off the failing command there. MySQL, SQL Server, and SQLite keep the failed record and everything below applies.
 
 
 ### Finding the Failure
@@ -264,10 +278,10 @@ Press Enter to see which file failed:
 ```
   [OK]  001_create-table.sql      (0.3s)
   [ERR] 002_add-constraint.sql    (0.1s)
-  [-]   003_add-index.sql         - not executed
+  [-]   003_add-index.sql         - 002_add-constraint.sql failed: ...
 ```
 
-The third file was never executed because the second one failed. This tells you exactly where to start looking.
+The third file was never executed because the second one failed, and its skip reason names the culprit. This tells you exactly where to start looking.
 
 
 ### Reading the Error
@@ -302,7 +316,7 @@ After fixing the issue:
 
 ## History Retention
 
-History is stored in the noorm tracking tables (`__noorm_change__` and `__noorm_executions__`). These tables grow with usage.
+History is stored in noorm’s change tracking tables, described in [Execution](/guide/sql-files/execution#what-gets-tracked). These tables grow with usage.
 
 For long-running projects, consider:
 
diff --git a/docs/guide/changes/overview.md b/docs/guide/changes/overview.md
index a77289a1..1da4fbd2 100644
--- a/docs/guide/changes/overview.md
+++ b/docs/guide/changes/overview.md
@@ -226,6 +226,10 @@ Each change has a status:
 | `success` | Applied successfully |
 | `failed` | Last execution failed |
 | `reverted` | Was applied, then rolled back |
+| `stale` | Was applied, then `db teardown` dropped the objects it created |
+
+`pending`, `reverted`, and `stale` all count as outstanding work, so `change ff` and
+`change next` pick up all three.
 
 From the headless CLI, `noorm change list` prints every known change with its status. Bare `noorm change` renders help -- it does not connect to the database.
 
@@ -235,13 +239,34 @@ noorm change list --json      # Same data as JSON
 ```
 
 ```json
-[
-    { "name": "2025-01-15-add-email-verification", "status": "success" },
-    { "name": "2025-02-01-migrate-user-roles", "status": "pending" }
-]
+{
+    "success": true,
+    "changes": [
+        {
+            "name": "2025-01-15-add-email-verification",
+            "status": "success",
+            "appliedAt": "2025-01-15T14:30:00.000Z",
+            "appliedBy": "Alice <alice@example.com>",
+            "revertedAt": null,
+            "errorMessage": null,
+            "isNew": false,
+            "orphaned": false
+        }
+    ],
+    "pending": 1
+}
 ```
 
-When you omit the change name on a TTY, the `run`, `revert`, `rewind`, `edit`, `rm`, and `history-detail` subcommands open an interactive picker filtered to the relevant subset (pending for `run`, applied for `revert`/`rewind`, etc.). Non-TTY callers must supply the name.
+Each entry merges the database record above with the on-disk one, so it also carries
+`path`, `date`, `description`, `changeFiles`, `revertFiles`, and `hasChangelog`. An entry
+flagged `orphaned` exists in the change tracking tables but no longer on disk, so those
+disk fields are absent.
+
+When you omit the change name on a TTY, several subcommands open an interactive picker.
+`run`, `revert`, `rewind`, and `history-detail` query the database and filter to the
+relevant subset: outstanding changes for `run`, successfully applied ones for `revert` and
+`rewind`, anything with a history record for `history-detail`. `edit` and `rm` work offline
+and list every folder in `changes/`. Non-TTY callers must supply the name.
 
 
 ## Common Workflows
@@ -299,28 +324,41 @@ Revert the last N applied changes:
 noorm change rewind 3
 ```
 
-This reverts the three most recently applied changes, starting with the newest.
+This reverts the three most recently applied changes, starting with the newest. Pass a
+change name instead of a count to rewind back to and including that change:
+
+```bash
+noorm change rewind 2025-01-15-add-email-verification
+```
 
 
 ### Preview Before Running
 
-See what SQL will execute without running it:
+`--dry-run` is the preview: it renders every file, templates and manifests included, and
+writes the result under `tmp/` instead of executing it. See [Dry Run](#dry-run) below.
+
+To render a single template file to stdout without involving a change at all, use
+`noorm run preview`:
 
 ```bash
-noorm change run 2025-02-01-migrate-user-roles --preview
+noorm run preview sql/views/user_summary.sql.tmpl
 ```
 
-For templates, this shows the rendered SQL. Use this before running against production.
-
 
 ### Dry Run
 
-Render files to a temporary directory without executing. Available on every apply/revert command: `change run`, `change revert`, `change ff`, and `change next`:
+Render files to a temporary directory without executing. Available on every apply/revert command: `change run`, `change revert`, `change ff`, `change next`, and `change rewind`:
 
     noorm change run 2025-02-01-migrate-user-roles --dry-run
     noorm change ff --dry-run
 
-Files are written to `tmp/` so you can inspect them. The dry-run branch does **not** consult the tracking tables (`__noorm_change__`, `__noorm_executions__`) and never writes to them — making it safe to run repeatedly in production. The CLI tags human output with `(dry-run)` and adds `dryRun: true` to the JSON payload so CI pipelines can verify the result didn't touch the database.
+Files are written to `tmp/` so you can inspect them. A dry run never writes to the change
+tracking tables: it skips the "does this need to run?" lookup, takes no lock, and creates
+no history record, which makes it safe to run repeatedly in production. `ff`, `next`, and
+`rewind` still read the tables to work out which changes to render. The CLI tags human
+output with `(dry-run)` and adds `dryRun: true` to the JSON payload of `run`, `revert`,
+`ff`, and `next` so CI pipelines can verify the result didn't touch the database.
+`rewind --json` does not add the flag.
 
 
 ## When Changes Re-Run
@@ -337,7 +375,7 @@ noorm tracks whether each change needs to run based on several conditions:
 | `--force` flag provided | Runs |
 | Successfully applied, unchanged | Skipped |
 
-After a successful run, the change won't run again unless something changes. This is tracked via checksums of all files in `change/` or `revert/`.
+After a successful run, the change won't run again unless something changes. This is tracked via a combined checksum of every file in `change/` or `revert/` plus the schema files any `.txt` manifest references, so editing a referenced view or function re-triggers the change.
 
 ::: tip Force Re-Run
 Need to re-apply a change? Use `--force`:
@@ -359,7 +397,7 @@ noorm change run my-change --force
 
 **Use manifests for shared SQL.** Reference existing schema files with `.txt` manifests instead of duplicating SQL.
 
-**Preview before production.** Use `--preview` or `--dry-run` to inspect exactly what will execute.
+**Preview before production.** Use `--dry-run` to render everything to `tmp/` and inspect exactly what will execute.
 
 **Write meaningful changelog.md files.** Explain *why* the change exists, not just what it does. Future debugging sessions will benefit.
 
diff --git a/docs/guide/database/create.md b/docs/guide/database/create.md
index 5f4880c1..3b693d6f 100644
--- a/docs/guide/database/create.md
+++ b/docs/guide/database/create.md
@@ -41,9 +41,19 @@ inherits the active config. `noorm run build`, `noorm change ff`, and
 ## What `noorm db create` does (and what it needs)
 
 The command connects to the dialect's *system database*
-(`postgres` for PostgreSQL, `master` for MSSQL; MySQL skips this) with
-the credentials in the named config, then runs the dialect's
-`CREATE DATABASE` statement targeted at `config.connection.database`.
+(`postgres` for PostgreSQL, `master` for MSSQL; MySQL connects with no
+database named at all) with the credentials in the named config, then
+runs the dialect's `CREATE DATABASE` statement targeted at
+`config.connection.database`. SQLite has no system database to borrow,
+so noorm checks that the directory holding the file is writable
+instead. That probe leaves nothing behind.
+
+Creating the database is only half the job. `db create` then connects
+to the new database and bootstraps noorm's own tracking tables
+(`version`, `change`, `executions`, `lock`, `identities`, `vault`), so
+the config is ready for `run build` and `change ff` when the command
+returns. Running it against a database that already exists and is
+already initialized is a no-op that reports `alreadyExists: true`.
 
 It needs:
 
@@ -51,6 +61,9 @@ It needs:
 - Credentials in the config that can reach the server.
 - A server-level permission to create databases (e.g. `CREATEDB` on
   PostgreSQL, `dbcreator` role on MSSQL).
+- An access role that permits `db:create`. A `viewer` config is denied
+  outright; an `operator` config needs `--yes` (or `NOORM_YES=1`) to
+  satisfy the confirmation; an `admin` config runs unconfirmed.
 
 It does not need:
 
@@ -58,6 +71,10 @@ It does not need:
 - A `.noorm/` schema to be built — `noorm run build` is a separate
   step.
 
+The access check runs before any probe touches the server. That
+ordering matters on SQLite, where merely opening the target creates the
+file: checking afterwards would hand a denied role a database anyway.
+
 
 ## Why no `--name <database>` flag?
 
@@ -80,13 +97,17 @@ Three reasons, in order of importance:
    reviewable artifact in your repo or CI runner.
 
 If you genuinely need ad-hoc database creation without a stored
-config, fall back to a one-shot SQL statement against the system
-database:
+config, fall back to a one-shot SQL statement issued through an
+existing one:
 
     noorm sql query -c dev "CREATE DATABASE foo"
 
-That's an explicit, dialect-aware path — and it forces you to pick
-a config (and therefore a connection identity) for the operation.
+That forces you to pick a config, and therefore a connection identity,
+for the operation. Two caveats: the statement runs against the `dev`
+database rather than the system database, so `dev` itself has to exist
+and be reachable; and `CREATE DATABASE` classifies as `sql:ddl`, which
+only an `admin`-role config may run. The SQL is passed through
+verbatim, so it is on you to write it for the right dialect.
 
 
 ## Companion commands
@@ -99,6 +120,12 @@ a config (and therefore a connection identity) for the operation.
 | `noorm db create [-c <name>]` | Create the database described by the named config. |
 | `noorm db drop [-c <name>]` | Drop the database described by the named config. |
 
+`db drop` is gated harder than `db create`. Its `db:destroy` permission
+denies both `viewer` and `operator`, and an `admin` config still has to
+confirm, so dropping a database always takes `--yes` (or `NOORM_YES=1`).
+A config using the default access role is `user: admin`, which is why
+`db create` needs no flag on a fresh project.
+
 For interactive setup (when you're at a terminal), `noorm ui` launches
 a wizard that walks through identity → config → DB create in order.
 Scripted setups should stick with the `import` + `create` flow above.
diff --git a/docs/guide/database/explore.md b/docs/guide/database/explore.md
index 3d6dcdae..797639f2 100644
--- a/docs/guide/database/explore.md
+++ b/docs/guide/database/explore.md
@@ -1,7 +1,7 @@
 # Schema Explorer
 
 
-The Schema Explorer gives you read-only access to your database structure directly from the terminal. No need to switch to pgAdmin, MySQL Workbench, or Azure Data Studio. Browse tables, views, indexes, foreign keys, functions, procedures, and types without leaving your workflow.
+The Schema Explorer gives you read-only access to your database structure directly from the terminal. No need to switch to pgAdmin, MySQL Workbench, or Azure Data Studio. Browse tables, views, indexes, foreign keys, functions, procedures, types, and triggers without leaving your workflow.
 
 
 ## What It Shows
@@ -17,6 +17,20 @@ The explorer queries your database's system catalogs to reveal its structure:
 | Functions | Parameters, return type, definition |
 | Procedures | Parameters, definition |
 | Types | Enum values, composite attributes, domain base types |
+| Triggers | Table, timing (BEFORE/AFTER/INSTEAD OF), events, definition |
+
+Two more categories, **locks** and **connections**, describe runtime state rather than schema. They are counted in the `--json` overview and reachable from the SDK, but they have no CLI listing and no TUI screen.
+
+Which catalogs each dialect reads:
+
+| Dialect | Catalogs |
+|---------|----------|
+| PostgreSQL | `information_schema` for tables, columns, views, FKs, and parameters; `pg_catalog` (`pg_proc`, `pg_type`, `pg_enum`, `pg_indexes`, `pg_locks`, `pg_stat_activity`) for everything it cannot express |
+| MySQL | `information_schema` throughout, plus `performance_schema.metadata_locks` for locks |
+| MSSQL | `sys.*` catalog views (`sys.tables`, `sys.views`, `sys.procedures`, `sys.types`, `sys.indexes`, `sys.foreign_keys`, `sys.triggers`) |
+| SQLite | `sqlite_master` for object names and DDL, `PRAGMA table_info` / `index_info` / `foreign_key_list` for the rest |
+
+noorm's own tracking objects are filtered out: PostgreSQL and MSSQL exclude the `noorm` schema in the catalog query, MySQL and SQLite drop names starting with `__noorm_`. Set the log level to `verbose` to include them.
 
 
 ## Accessing the Explorer
@@ -24,25 +38,29 @@ The explorer queries your database's system catalogs to reveal its structure:
 
 ### Terminal UI
 
-From the home screen, press `d` to enter the Database menu, then `e` to explore:
+From the home screen, press `d` to enter the Database menu, then `x` to explore:
 
 ```
-Home → [d] Database → [e] Explore
+Home → [d] Database → [x] Explore
 ```
 
-Or navigate directly through the menu:
+The Database menu:
 
 ```
 ┌─ Database ──────────────────────────────────────────────────┐
 │                                                             │
-│  [e] explore       Browse tables, views, indexes            │
-│  [t] terminal      Interactive SQL REPL                     │
-│  [w] truncate      Wipe all data (keep schema)              │
-│  [x] teardown      Drop all objects                         │
+│  [c] create        Create the database for this config      │
+│  [d] destroy       Drop the database for this config        │
+│  [x] explore       Browse tables, views, indexes            │
+│  [w] wipe          Truncate all data (keep schema)          │
+│  [t] teardown      Drop all objects                         │
+│  [r] transfer      Move data between configs                │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
 
+The SQL terminal is not on this menu. Press `Shift+Q` from anywhere, or run `noorm sql repl`. See [SQL Terminal](/guide/database/terminal).
+
 
 ### Scripted Usage
 
@@ -52,9 +70,14 @@ The same subcommands run non-interactively — add `--json` to get machine-reada
 noorm db explore                          # Overview
 noorm db explore tables                   # List tables
 noorm db explore tables detail users      # Table detail
+noorm db explore fks                      # List foreign keys
+noorm db explore triggers                 # List triggers
+noorm db explore tables --schema app      # Restrict to one schema
 noorm db explore --json > schema.json     # JSON output
 ```
 
+The subcommands are `tables`, `views`, `procedures`, `functions`, `types`, `indexes`, `fks`, and `triggers`. Every one accepts `--schema` except on SQLite, which has no schemas and rejects the flag rather than returning an empty list. `tables`, `views`, `procedures`, `functions`, `types`, and `triggers` also take a `detail <name>` subcommand.
+
 
 ## Overview Screen
 
@@ -91,6 +114,8 @@ Press the number key or hotkey to drill into any category. Categories with zero
 | `6` | `i` | Indexes |
 | `7` | `k` | Foreign Keys |
 
+The TUI overview lists these seven. `noorm db explore` on the command line prints a Triggers count as well, and `--json` carries all ten counters including locks and connections. The Total Objects figure sums every counter the overview computed, so it can exceed the seven rows on screen when triggers, locks, or connections are present.
+
 
 ## Browsing Tables
 
@@ -336,7 +361,7 @@ Custom types are available in PostgreSQL and MSSQL. The explorer shows enum valu
 
 ## Headless JSON Output
 
-Use `--json` flag for machine-readable output.
+Use `--json` flag for machine-readable output. Every noorm command wraps its `--json` payload in an object carrying a top-level `success` boolean, so `jq -e '.success'` works the same way against all of them. A list is never emitted as a bare array; it is always named, as in `{ "tables": [...] }`.
 
 
 ### Overview
@@ -347,13 +372,17 @@ noorm db explore --json
 
 ```json
 {
+    "success": true,
     "tables": 12,
     "views": 3,
     "procedures": 0,
     "functions": 5,
     "types": 2,
     "indexes": 18,
-    "foreignKeys": 7
+    "foreignKeys": 7,
+    "triggers": 4,
+    "locks": 0,
+    "connections": 2
 }
 ```
 
@@ -365,13 +394,18 @@ noorm db explore tables --json
 ```
 
 ```json
-[
-    { "name": "users", "schema": "public", "columnCount": 8, "rowCountEstimate": 1500 },
-    { "name": "posts", "schema": "public", "columnCount": 5, "rowCountEstimate": 42000 },
-    { "name": "comments", "schema": "public", "columnCount": 4, "rowCountEstimate": 128000 }
-]
+{
+    "success": true,
+    "tables": [
+        { "name": "users", "schema": "public", "columnCount": 8, "rowCountEstimate": 1500 },
+        { "name": "posts", "schema": "public", "columnCount": 5, "rowCountEstimate": 42000 },
+        { "name": "comments", "schema": "public", "columnCount": 4, "rowCountEstimate": 128000 }
+    ]
+}
 ```
 
+The other list subcommands follow the same shape under their own key: `views`, `procedures`, `functions`, `types`, `indexes`, `foreignKeys` (from `noorm db explore fks`), and `triggers`.
+
 
 ### Table Detail
 
@@ -381,6 +415,7 @@ noorm db explore tables detail users --json
 
 ```json
 {
+    "success": true,
     "name": "users",
     "schema": "public",
     "columns": [
@@ -407,6 +442,7 @@ noorm db explore views detail active_users --json
 
 ```json
 {
+    "success": true,
     "name": "active_users",
     "schema": "public",
     "columns": [
@@ -427,6 +463,7 @@ noorm db explore functions detail calculate_total --json
 
 ```json
 {
+    "success": true,
     "name": "calculate_total",
     "schema": "public",
     "parameters": [
@@ -449,11 +486,14 @@ The explorer works across all supported databases with appropriate translations:
 | Views | Yes | Yes | Yes | Yes |
 | Indexes | Yes | Yes | Yes | Yes |
 | Foreign Keys | Yes | Yes | Yes | Yes |
+| Triggers | Yes | Yes | Yes | Yes |
 | Functions | Yes | Yes | Yes | -- |
 | Procedures | Yes | Yes | Yes | -- |
 | Types | Yes | -- | Yes | -- |
+| Locks | Yes | Yes | Yes | -- |
+| Connections | Yes | Yes | Yes | -- |
 
-SQLite does not support stored procedures, functions, or user-defined types. MySQL does not support user-defined types. These categories return empty results for unsupported dialects.
+SQLite does not support stored procedures, functions, or user-defined types, and has no server to report locks or connections for. MySQL does not support user-defined types. These categories return empty results for unsupported dialects.
 
 **Type support by dialect:**
 
diff --git a/docs/guide/database/teardown.md b/docs/guide/database/teardown.md
index 5a9abcef..c3da576d 100644
--- a/docs/guide/database/teardown.md
+++ b/docs/guide/database/teardown.md
@@ -19,7 +19,7 @@ noorm provides controlled reset operations that complete in milliseconds while h
 | `teardown` | Drop all database objects | Full rebuild, change testing |
 
 ::: danger Destructive Operations
-Both operations permanently destroy data. `truncate` wipes all rows. `teardown` drops tables, views, functions, and types. There is no undo. These commands require explicit confirmation.
+Both operations permanently destroy data. `truncate` wipes all rows. `teardown` drops tables, views, functions, procedures, types, and foreign key constraints. There is no undo. These commands require explicit confirmation.
 :::
 
 
@@ -34,14 +34,16 @@ noorm db truncate -y
 ### What Gets Truncated
 
 - All user tables (rows deleted)
-- Identity/auto-increment sequences reset to 1
+- Identity/auto-increment counters restarted, on every dialect except SQLite
 - Foreign key constraints temporarily disabled during operation
 
+Foreign key enforcement is re-enabled even when the truncate itself fails partway through, so a failed run never leaves the database with constraints switched off.
+
 ### What Stays
 
 - Table definitions and indexes
 - Views, functions, stored procedures
-- noorm internal tables (`__noorm_*`)
+- noorm internal tracking tables (the `noorm` schema, or `__noorm_*__` tables)
 
 
 ## Teardown: Drop Everything
@@ -53,7 +55,7 @@ noorm db teardown -y
 ```
 
 ::: warning Access Roles
-`db teardown` is gated by the config's `db:reset` access role: `viewer` is denied outright, `operator` must confirm (`yes-<config>`, or `NOORM_YES=1` in CI), `admin` runs unconfirmed — see [Access Roles](#access-roles) below.
+`db teardown` is gated by the config's `db:teardown` permission: `viewer` and `operator` are both denied outright, and even `admin` must confirm (`yes-<config>`, or `NOORM_YES=1` in CI). Only an `admin`-role config can tear down at all. See [Access Roles](#access-roles) below.
 :::
 
 ### Drop Order
@@ -61,27 +63,35 @@ noorm db teardown -y
 Objects are removed in dependency-safe order:
 
 1. **Foreign key constraints** - Must go first to allow table drops
-2. **Views** - May depend on tables
-3. **Tables** - Core schema objects
-4. **Functions/Procedures** - May depend on types
-5. **Types** - Enum and composite types last
+2. **CHECK constraints** - MSSQL only, and only when functions are being dropped: a scalar UDF referenced by a CHECK constraint cannot be dropped while its table stands
+3. **Procedures** - Dropped early so they hold no references to the functions, views, and tables below
+4. **Functions** - Must precede table drops so schema-bound UDFs release their dependency locks
+5. **Views** - Schema-bound views also lock the tables they reference
+6. **Tables** - Safe once every schema-bound dependent is gone
+7. **Types** - Table types first, then the rest
+
+Procedures, functions, and views all go before tables, not after. A `WITH SCHEMABINDING` object on MSSQL holds a dependency lock on the table it references, and dropping the table first fails with "Cannot DROP TABLE ... because it is being referenced by object ...".
 
 You do not need to manage this ordering. noorm handles it automatically.
 
+Pass `--preserve-schemas <a,b>` to leave whole schemas untouched. Teardown reaches every non-system schema, so this is the way to protect one it did not create.
+
 ### What Stays
 
 noorm internal tables are always preserved:
 
-- `__noorm_change__` - Change execution history
-- `__noorm_executions__` - File execution records
-- `__noorm_locks__` - Active operation locks
+- `change` - Change execution history
+- `executions` - File execution records
+- `lock` - Active operation locks
+
+On PostgreSQL and SQL Server these live in a dedicated `noorm` schema, so they read as `noorm.change`, `noorm.executions`, and `noorm.lock`. MySQL and SQLite have no schemas, so they keep the prefixed forms in the default schema: `__noorm_change__`, `__noorm_executions__`, `__noorm_lock__`.
 
 After teardown, noorm can still track what was applied previously. Changes are marked as `stale`, meaning they'll re-run on the next [fast-forward](/guide/changes/forward-revert). See [History](/guide/changes/history) for how this affects your execution log.
 
 
 ## Access Roles
 
-[Configs](/guide/environments/configs) declare an `access.user` role — `viewer`, `operator`, or `admin` — that gates `db teardown` (and `truncate`, `reset`) via the `db:reset` permission. This prevents accidentally wiping production data. You can also cap it at the [stage level](/guide/environments/stages): a stage with `protected: true` clamps every linked config's resolved access to at most `operator`/`viewer`.
+[Configs](/guide/environments/configs) declare an `access.user` role — `viewer`, `operator`, or `admin` — and each destructive operation resolves against its own permission, not one shared one. This prevents accidentally wiping production data. You can also cap it at the [stage level](/guide/environments/stages): a stage with `protected: true` clamps every linked config's resolved access to at most `operator`/`viewer`.
 
 ```yaml
 # .noorm/settings.yml
@@ -91,15 +101,25 @@ stages:
             protected: true   # access ceiling: at most operator/viewer
 ```
 
-When you attempt teardown on a `viewer`-role config:
+The three permissions in this family resolve differently:
+
+| Operation | Permission | `viewer` | `operator` | `admin` |
+|-----------|------------|----------|------------|---------|
+| `db teardown` | `db:teardown` | Denied | Denied | Confirm |
+| `db truncate` | `db:truncate` | Denied | Confirm | Confirm |
+| `db reset` / `ctx.noorm.db.reset()` | `db:reset` | Denied | Confirm | Allowed |
+
+Teardown is the strictest of the three: it is the only one an `operator` cannot reach at all, and the only one that still asks an `admin` to confirm. `reset` is the loosest, because it rebuilds the schema it just dropped.
+
+When you attempt teardown on a `viewer`- or `operator`-role config:
 
 ```
-Cannot teardown on config "prod": "db:reset" is not allowed on config "prod" (role: viewer)
+Cannot teardown on config "prod": "db:teardown" is not allowed on config "prod" (role: operator)
 ```
 
-An `operator`-role config doesn't refuse teardown — it asks for confirmation instead (see below).
+No flag, environment variable, or SDK option overrides a denial. Give the config `admin` access if it genuinely needs to be torn down.
 
-### Confirming on `operator`
+### Confirming on `admin`
 
 **CLI/TUI**: Type the confirmation phrase, or pass `--yes` (`NOORM_YES=1` in CI) to skip the prompt:
 
@@ -107,15 +127,19 @@ An `operator`-role config doesn't refuse teardown — it asks for confirmation i
 NOORM_YES=1 noorm db teardown --config prod
 ```
 
-**SDK**: There is no prompt to answer. `ctx.noorm.db.teardown()` throws `ProtectedConfigError` on an `operator`-role config unless `NOORM_YES=1` is set in the environment — the same variable the CLI honors:
+**SDK**: There is no prompt to answer. `ctx.noorm.db.teardown()` throws `ProtectedConfigError` on any config whose confirmation the caller has not pre-supplied. Pass `yes: true` to `createContext`, or set `NOORM_YES=1` in the environment, the same variable the CLI honors:
 
 ```typescript
-const ctx = await createContext({ config: 'prod' })
+const ctx = await createContext({ config: 'prod', yes: true })
 
-await ctx.noorm.db.teardown()  // Throws ProtectedConfigError on operator; run via CLI/TUI or set NOORM_YES=1
+await ctx.noorm.db.teardown()  // Throws ProtectedConfigError without `yes` (or NOORM_YES=1)
 ```
 
-A `viewer`-role config denies `db teardown` outright — no flag, environment variable, or SDK option overrides that. Give the config `admin` access if it genuinely needs frictionless teardown.
+Neither `yes: true` nor `NOORM_YES=1` unblocks a denial. On a `viewer`- or `operator`-role config, `teardown()` throws no matter what you pass.
+
+A dry run is checked against the role but never against the confirmation: any role allowed to tear down can preview one without `--yes`. Previewing is the safety mechanism, so it stays reachable.
+
+Contexts created on the `agent` channel (MCP, or an AI agent driving the CLI) never satisfy a confirmation at all. `confirm` collapses to `deny` before `yes` is consulted, so an agent cannot walk through a gate a human was meant to answer.
 
 ::: danger
 Running teardown against production should be exceedingly rare. If you find yourself doing this regularly, reconsider your deployment workflow.
@@ -138,6 +162,8 @@ teardown:
 
 These tables will be skipped during both truncate and teardown operations. Their data and structure remain intact.
 
+`ctx.noorm.db.reset()` is the exception: it ignores `preserveTables` on purpose. Reset rebuilds the whole schema from `sql/`, so any table left standing would collide with the build's `CREATE TABLE` and abort the rebuild.
+
 
 ## Post-Teardown Scripts
 
@@ -235,7 +261,7 @@ beforeAll(async () => {
 })
 ```
 
-The `reset()` method combines `ctx.noorm.db.teardown()` and `ctx.noorm.run.build({ force: true })` for complete schema reconstruction.
+The `reset()` method combines a full teardown with `run.build({ force: true })` for complete schema reconstruction. It is gated by `db:reset`, which an `admin`-role config satisfies without confirmation.
 
 
 ## Scripted Usage
@@ -258,23 +284,28 @@ noorm db teardown --dry-run
 ### JSON Output
 
 ```bash
-noorm db teardown --json
+noorm db teardown --json --yes
 ```
 
 ```json
 {
-    "status": "success",
+    "success": true,
     "dropped": {
         "tables": ["users", "posts", "comments"],
         "views": ["active_users"],
         "functions": [],
-        "types": []
+        "procedures": [],
+        "types": [],
+        "foreignKeys": ["posts_user_id_fkey"]
     },
-    "preserved": ["countries", "app_settings"],
-    "durationMs": 45
+    "count": 4
 }
 ```
 
+`count` sums tables, views, functions, and types, but not procedures or foreign keys. A dry run adds `"dryRun": true`, and a configured post-script adds `postScriptResult`. When a post-script fails, the objects are still gone but the command exits non-zero, because a teardown whose seeding step never ran is half-finished.
+
+`noorm db truncate --json` reports `truncated`, `preserved`, and `count`, plus `statements` on a dry run.
+
 ### CI/CD Pattern
 
 ```yaml
@@ -330,12 +361,14 @@ noorm generates appropriate SQL for each database:
 
 | Feature | PostgreSQL | MySQL | MSSQL | SQLite |
 |---------|------------|-------|-------|--------|
-| Truncate | `TRUNCATE TABLE` | `TRUNCATE TABLE` | `TRUNCATE TABLE` | `DELETE FROM` |
-| Reset identity | `RESTART IDENTITY` | `AUTO_INCREMENT = 1` | `DBCC CHECKIDENT RESEED` | N/A |
-| Disable FKs | `SET session_replication_role` | `SET FOREIGN_KEY_CHECKS=0` | `NOCHECK CONSTRAINT` | `PRAGMA foreign_keys=OFF` |
+| Truncate | `TRUNCATE TABLE ... CASCADE` | `TRUNCATE TABLE` | `DELETE FROM` | `DELETE FROM` |
+| Reset identity | `RESTART IDENTITY` | Automatic with `TRUNCATE` | `DBCC CHECKIDENT ... RESEED` | N/A |
+| Disable FKs | `SET session_replication_role` | `SET FOREIGN_KEY_CHECKS=0` | Per-table `NOCHECK CONSTRAINT` | `PRAGMA foreign_keys=OFF` |
 | Drop cascade | `CASCADE` | Manual order | Manual order | Manual order |
 
-SQLite uses DELETE instead of TRUNCATE because SQLite does not support TRUNCATE.
+Two dialects use DELETE rather than TRUNCATE, for different reasons. SQLite has no TRUNCATE statement. MSSQL has one, but it refuses to run against a table referenced by a foreign key even with constraints set to NOCHECK, so noorm issues a DELETE and reseeds the identity separately.
+
+MSSQL also has no session-level foreign key switch, so noorm emits one `ALTER TABLE ... NOCHECK CONSTRAINT ALL` per table rather than using `sp_MSforeachtable`, whose parallel workers deadlock on schema locks.
 
 
 ## Best Practices
@@ -348,7 +381,7 @@ SQLite uses DELETE instead of TRUNCATE because SQLite does not support TRUNCATE.
 
 **Use postScript for seeds.** Re-insert required data automatically after teardown.
 
-**Check the config's access role.** A `viewer`/`operator` role exists for a reason. Think twice before switching a config to `admin` just to skip the confirmation.
+**Check the config's access role.** A `viewer`/`operator` role exists for a reason. Switching a config to `admin` is what makes teardown possible at all, so think twice before doing it to get past a denial.
 
 ```bash
 # Safe teardown pattern
diff --git a/docs/guide/database/terminal.md b/docs/guide/database/terminal.md
index 02b7f16b..e31e5f70 100644
--- a/docs/guide/database/terminal.md
+++ b/docs/guide/database/terminal.md
@@ -10,12 +10,17 @@ Debugging a change? Check if that INSERT worked. Exploring a table structure? Ru
 
 ## Launching the Terminal
 
-From the home screen, press `d` for database, then `t` for terminal:
+Press `Shift+Q` from anywhere in the TUI. The terminal is a global shortcut, not an entry on the Database menu, so there is no `[d]` then `[t]` path to it. On the Database screen, `t` is teardown.
 
-```
-Home → [d] Database → [t] Terminal
+From a shell, launch straight into it:
+
+```bash
+noorm sql repl              # active config
+noorm sql repl --config dev # a specific config
 ```
 
+`noorm sql repl` opens the same TUI screen, so everything on this page applies to both. It needs an interactive terminal and refuses to run under `--yes` or `NOORM_YES`; for scripted SQL use `noorm sql query "SELECT 1"` or `noorm sql query -f query.sql` instead.
+
 The terminal connects to your [active configuration](/guide/environments/configs) automatically.
 
 
@@ -24,7 +29,7 @@ The terminal connects to your [active configuration](/guide/environments/configs
 ```
 ┌─ SQL Terminal ──────────────────────────────────────────────┐
 │                                                             │
-│  noorm> SELECT * FROM users LIMIT 3;                        │
+│  > SELECT * FROM users LIMIT 3;                             │
 │                                                             │
 │  ┌────┬─────────┬─────────────────┬─────────────────────┐   │
 │  │ id │ name    │ email           │ created_at          │   │
@@ -36,23 +41,47 @@ The terminal connects to your [active configuration](/guide/environments/configs
 │                                                             │
 │  3 rows (12ms)                                              │
 │                                                             │
-│  noorm> _                                                   │
+│  > _                                                        │
 │                                                             │
-│  [h] history   [c] clear                                    │
+│  [Shift+Tab] Edit mode  [Enter] Execute  [Shift+Enter] New  │
+│  [h] History   [Esc] Clear                                  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-Type your SQL at the `noorm>` prompt and press Enter to execute.
+Type your SQL at the `>` prompt and press Enter to execute. The prompt changes to `[EDIT]>` in edit mode, where Enter inserts a newline instead of running the query.
+
+
+## What You Are Allowed to Run
+
+Before anything reaches the database, noorm classifies the statement and checks that class against the [config's access role](/guide/environments/configs):
+
+| Class | Permission | `viewer` | `operator` | `admin` |
+|-------|------------|----------|------------|---------|
+| Reads (`SELECT`, `SHOW`, `DESCRIBE`) | `sql:read` | Yes | Yes | Yes |
+| Writes (`INSERT`, `UPDATE`, `DELETE`, `MERGE`) | `sql:write` | No | Yes | Yes |
+| Everything else | `sql:ddl` | No | No | Yes |
+
+`sql:ddl` is the catch-all, not a DDL-keyword list. `CREATE`/`ALTER`/`DROP`/`TRUNCATE`/`GRANT`/`REVOKE`/`SET`, `EXEC`/`CALL`, and anything the classifier cannot make sense of all land there. Unrecognized input fails closed, on the reasoning that a statement nobody can classify could do anything.
+
+Classification looks past the outer keyword, which matters more than it sounds:
+
+- A statement is parsed, not pattern-matched, and the **highest** class anywhere in the tree wins. `WITH t AS (DELETE FROM logs ...) SELECT * FROM t` is a write, not a read.
+- `EXPLAIN` takes the class of the statement it wraps, because `EXPLAIN ANALYZE` executes that statement. `EXPLAIN (ANALYZE) DELETE FROM t` is a write.
+- `SELECT ... INTO` creates a table or writes a file, so it classifies as `sql:ddl` rather than a read.
+- A `SELECT` calling a side-effecting or filesystem builtin (`pg_terminate_backend`, `setval`, `pg_read_file`, and similar) is raised to `sql:write`, which is the lowest class a `viewer` cannot reach.
+- Multi-statement input takes the highest class present, so one `DROP` after a semicolon governs the whole submission.
+
+The denylist behind that last rule covers known-dangerous builtins, not every function that could have a side effect. It stops casual and accidental writes on a `viewer` config; it is not a sandbox for a determined adversary.
 
 
 ## Running Queries
 
-The terminal supports any SQL your database understands:
+The terminal runs any SQL your database understands, subject to the access role above:
 
 **SELECT queries** return formatted tables with timing:
 
 ```
-noorm> SELECT id, email FROM users WHERE active = true LIMIT 5;
+> SELECT id, email FROM users WHERE active = true LIMIT 5;
 
 ┌────┬────────────────────┐
 │ id │ email              │
@@ -67,15 +96,15 @@ noorm> SELECT id, email FROM users WHERE active = true LIMIT 5;
 **INSERT, UPDATE, DELETE** report affected rows:
 
 ```
-noorm> UPDATE users SET last_login = NOW() WHERE id = 1;
+> UPDATE users SET last_login = NOW() WHERE id = 1;
 
 1 row affected (5ms)
 ```
 
-**DDL statements** (CREATE, ALTER, DROP) work too:
+**DDL statements** (CREATE, ALTER, DROP) work too, on an `admin`-role config:
 
 ```
-noorm> CREATE INDEX users_email_idx ON users(email);
+> CREATE INDEX users_email_idx ON users(email);
 
 OK (42ms)
 ```
@@ -96,12 +125,22 @@ Results display in a formatted table with column alignment:
 2 rows (15ms)
 ```
 
-Long values are truncated with ellipsis to fit the screen. Select a row to view full cell contents in the detail view.
+Long values are truncated with an ellipsis to fit the column. There is no per-cell detail view, so to read a value in full, re-run the query selecting fewer columns.
+
+Once a query returns rows, press `Tab` to move into the results table. From there:
+
+| Key | Action |
+|-----|--------|
+| `↑` / `↓` | Navigate rows |
+| `/` | Filter rows |
+| `s` | Sort by a column |
+| `c` | Clear the filter and sort |
+| `Tab` or `Esc` | Return to the query input |
 
 Errors display inline with the original query:
 
 ```
-noorm> SELECT * FROM nonexistent;
+> SELECT * FROM nonexistent;
 
 Error: relation "nonexistent" does not exist
 ```
@@ -114,7 +153,7 @@ Every query you run is saved. Browse and re-execute past queries without retypin
 
 ### Browsing History
 
-Press `h` to open the history viewer:
+Press `h` to open the history viewer. The input must be empty, so clear the prompt first:
 
 ```
 ┌─ Query History ─────────────────────────────────────────────┐
@@ -124,83 +163,62 @@ Press `h` to open the history viewer:
 │  3. SELECT * FROM nonexistent               -    ✗  2h ago  │
 │  4. INSERT INTO logs (msg) VALUES...        8ms  ✓  3h ago  │
 │                                                             │
-│  [Enter] re-run   [v] view results   [/] search             │
+│  [r] Re-run  [Enter] View result  [c] Clear  [↑/↓] Navigate │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 - `✓` indicates successful queries
 - `✗` indicates failed queries
-- Select an entry and press Enter to re-run it
+- `r` sends the selected query back to the terminal, pre-filled and ready to edit before you run it
+- `Enter` opens the stored results for that entry
 
-
-### Searching History
-
-Press `/` in the history view to search:
-
-```
-Search: users
-
-┌─ Query History (filtered) ──────────────────────────────────┐
-│                                                             │
-│  1. SELECT * FROM users LIMIT 10           12ms  ✓  1h ago  │
-│  2. UPDATE users SET active = true...       5ms  ✓  2h ago  │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
+The history viewer has no search. To find an old query, scroll with the arrow keys.
 
 
 ### Viewing Saved Results
 
-Select a history entry and press `v` to view the full results from when the query ran. Results are stored compressed, so you can review query output even after the data has changed.
+Select a history entry and press `Enter` to view the full results from when the query ran. Results are stored gzipped, so you can review query output even after the data has changed.
 
+Only queries that returned rows have stored results. Pressing `Enter` on a failed entry shows its error message instead, and on a row-less entry it tells you there is nothing stored.
 
-## Tab Completion
 
-Press Tab while typing to auto-complete:
+## Writing Multi-Line Queries
 
-- **Table names** - Type `SEL` then Tab to see suggestions
-- **Column names** - After typing a table name, Tab shows its columns
-
-```
-noorm> SELECT * FROM us[Tab]
-                      users
-                      user_roles
-                      user_sessions
-```
+The terminal has no tab completion. `Tab` inserts four spaces, so you can indent a query by hand.
 
-Tab completion pulls from your database schema, so it knows your actual tables and columns.
+There are two ways to write across several lines. `Shift+Enter` inserts a newline without running anything. For a longer statement, press `Shift+Tab` to enter edit mode, where plain `Enter` becomes a newline and the prompt changes to `[EDIT]>`. Press `Shift+Tab` again to leave edit mode and get Enter-to-execute back.
 
 
 ## Keyboard Shortcuts
 
 | Key | Action |
 |-----|--------|
-| `Enter` | Execute query |
-| `Up` / `Down` | Navigate command history |
-| `Tab` | Auto-complete table/column names |
-| `Ctrl+C` | Clear current input |
-| `Escape` | Exit terminal |
-| `h` | Open history viewer |
-| `c` | Clear history |
+| `Enter` | Execute query (insert a newline in edit mode) |
+| `Shift+Enter` | Insert a newline |
+| `Shift+Tab` | Toggle edit mode |
+| `Tab` | Insert four spaces, or move between the query and the results table once a query has returned rows |
+| `Up` / `Down` | Navigate command history when the input is empty, otherwise move the cursor |
+| `Left` / `Right` | Move the cursor |
+| `Escape` | Clear the input; on an empty input, leave the terminal |
+| `h` | Open the history viewer (empty input only) |
 
 
 ## Clearing History
 
-Press `c` from the terminal to open the clear menu:
+Open the history viewer with `h`, then press `c` for the clear menu:
 
 ```
 ┌─ Clear History ─────────────────────────────────────────────┐
 │                                                             │
-│  1. Older than 1 month                                      │
-│  2. Older than 3 months                                     │
-│  3. Clear all history                                       │
+│  1. Clear last 3 months                                     │
+│  2. Clear all history                                       │
 │                                                             │
 │  History: 47 entries, 2.3 MB stored                         │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-Select an option to remove old entries and free up space. Results files are deleted along with their history entries.
+"Clear last 3 months" removes entries older than three months and keeps the rest. Either option deletes the stored result files along with their history entries. `noorm sql clear` does the same job from a shell.
 
 
 ## Tips
@@ -210,12 +228,12 @@ Select an option to remove old entries and free up space. Results files are dele
 **Preview before modifying** - Run a SELECT with your WHERE clause before executing UPDATE or DELETE:
 
 ```
-noorm> SELECT id, email FROM users WHERE last_login < '2023-01-01';
+> SELECT id, email FROM users WHERE last_login < '2023-01-01';
 -- Review the results
-noorm> DELETE FROM users WHERE last_login < '2023-01-01';
+> DELETE FROM users WHERE last_login < '2023-01-01';
 ```
 
-**History is not encrypted** - Query text and results are stored in plaintext (gzipped). Avoid running queries that contain sensitive data like passwords or API keys.
+**History is not encrypted** - Query text sits in plain JSON at `.noorm/state/history/<config>.json`, and returned rows sit gzipped beside it in `.noorm/state/history/<config>/`. Neither is encrypted, unlike `state.enc`. Both are written owner-only (`0600`, in a `0700` directory), but anything a `SELECT` pulled out of a credentials or PII table is readable by your user account. Avoid running queries that contain passwords or API keys, and clear the history after one slips through.
 
 
 ## What's Next?
diff --git a/docs/guide/database/transfer.md b/docs/guide/database/transfer.md
index ff5f64f2..362b2520 100644
--- a/docs/guide/database/transfer.md
+++ b/docs/guide/database/transfer.md
@@ -15,12 +15,14 @@ The databases share the same schema—same tables, same columns. You need the da
 
 | Dialect | Supported | Same-server optimization | Cross-dialect |
 |---------|-----------|--------------------------|---------------|
-| PostgreSQL | Yes | Only within same database | Yes |
+| PostgreSQL | Yes | No | Yes |
 | MySQL | Yes | Yes (cross-database on same host) | Yes |
 | MSSQL | Yes | Yes (cross-database on same host) | Yes |
 | SQLite | No | — | — |
 
-Same-server optimization uses direct `INSERT...SELECT` SQL instead of reading data into the application and writing it back. Significantly faster for large datasets.
+Same-server optimization uses direct `INSERT...SELECT` SQL instead of reading data into the application and writing it back. Faster for large datasets.
+
+PostgreSQL never takes that path. Without `dblink` or `postgres_fdw` it cannot reach another database, and when both configs name the same database the statement degenerates into copying a table into itself. PostgreSQL transfers always run through the batch path instead.
 
 Cross-dialect transfers convert data types automatically through a universal type system. Most common types map cleanly; some dialect-specific features (like PostgreSQL arrays) become JSON in dialects that don't support them natively.
 
@@ -48,19 +50,21 @@ The TUI shows live progress per table with row counts and batch completion.
 
 ## Headless Mode
 
-The `--to` flag is required. Source defaults to the active config.
+Exactly one of `--to`, `--export`, or `--import` is required; they are mutually exclusive. The source is the active config unless `-c` names another.
 
 ```bash
 # Transfer all tables from active config to backup
 noorm db transfer --to backup
 
-# Specify source explicitly
-noorm db transfer staging --to production
+# Specify source explicitly with -c
+noorm db transfer -c staging --to production
 
 # Transfer specific tables only
 noorm db transfer --to backup --tables users,posts,comments
 ```
 
+There is no positional source argument. `noorm db transfer staging --to production` does not name `staging` as the source; use `-c staging` (or `--config staging`).
+
 ### Dry Run
 
 Preview what will happen without transferring anything:
@@ -138,10 +142,13 @@ Transfer result:
         }
     ],
     "totalRows": 1500,
-    "durationMs": 1234
+    "durationMs": 1234,
+    "fkChecksRestored": true
 }
 ```
 
+Check `fkChecksRestored`. When it is `false`, the transfer finished but foreign key enforcement could not be turned back on at the destination, and referential integrity is still disabled there until you re-enable it by hand. The CLI also writes a warning to stderr in that case.
+
 Dry run result:
 
 ```json
@@ -166,7 +173,7 @@ Dry run result:
 
 ## What Happens During a Transfer
 
-1. **Planning** — noorm reads the source schema, builds a foreign key dependency graph, and sorts tables so parents are transferred before children.
+1. **Planning** — noorm reads the source schema, builds a foreign key dependency graph, and sorts tables so parents are transferred before children. A circular foreign key relationship cannot be sorted, so noorm falls back to the source's own table order and records a warning in the plan.
 
 2. **FK checks disabled** — Foreign key constraints are temporarily disabled on the destination to avoid ordering issues within batches.
 
@@ -183,15 +190,18 @@ Dry run result:
 
 - Destination tables must **already exist** with compatible column structure
 - The noorm project must have configs for both source and destination databases
+- The destination config's access role must permit `db:reset`: `viewer` is denied, `operator` and `admin` may write. From the SDK, an `operator` destination needs `yes: true` on the context (or `NOORM_YES=1`), since there is no prompt to answer
 - For cross-dialect transfers, column types must be convertible (most are; check the dry-run output for warnings)
 
+noorm's own tracking tables are never transferred. They are filtered out of the plan on both ends.
+
 
 ## Common Patterns
 
 ### Seed a dev database from staging
 
 ```bash
-noorm db transfer staging --to local --truncate
+noorm db transfer -c staging --to local --truncate
 ```
 
 Clears the local database first, then copies everything from staging.
@@ -223,7 +233,7 @@ Only transfers the specified tables. FK dependencies between selected tables are
 ### CI/CD test data setup
 
 ```bash
-noorm db transfer staging --to ci-test --truncate --on-conflict fail --json
+noorm db transfer -c staging --to ci-test --truncate --on-conflict fail --json
 ```
 
 Clean transfer for test environments. JSON output for pipeline integration. Fails fast if anything goes wrong.
@@ -231,8 +241,8 @@ Clean transfer for test environments. JSON output for pipeline integration. Fail
 ### Cross-dialect migration
 
 ```bash
-noorm db transfer postgres-legacy --to mysql-new --dry-run
-noorm db transfer postgres-legacy --to mysql-new
+noorm db transfer -c postgres-legacy --to mysql-new --dry-run
+noorm db transfer -c postgres-legacy --to mysql-new
 ```
 
 Migrate from PostgreSQL to MySQL. Run `--dry-run` first to check for type conversion warnings.
@@ -246,15 +256,20 @@ Export data to portable `.dt` files for backup, sharing, or migration without a
 
 | Extension | Description |
 |-----------|-------------|
-| `.dt` | Plain text (human-readable) |
-| `.dtz` | Compressed (gzip) |
-| `.dtzx` | Encrypted + compressed (requires passphrase) |
+| `.dt` | Line-delimited JSON5, uncompressed and human-readable |
+| `.dtz` | The same content, gzipped |
+| `.dtzx` | Gzipped and AES-256-GCM encrypted (requires passphrase) |
+
+`.dt` and `.dtz` stream row by row on import. `.dtzx` is decrypted and inflated whole before the first row is read, so it carries a size ceiling the other two do not.
 
 ### Export to Files
 
-The `--tables` flag is required for export.
+`--tables` defaults to every table in the source. Pass it to narrow the export.
 
 ```bash
+# Export every table to a directory
+noorm db transfer --export ./backup/
+
 # Export single table
 noorm db transfer --export ./backup/users.dt --tables users
 
@@ -268,8 +283,12 @@ noorm db transfer --export ./backup/ --tables users,posts --compress
 noorm db transfer --export ./backup/ --tables users --passphrase "my-secret"
 ```
 
+An export that would write nothing is an error, not a silent success: both an empty `--tables` list and a source with no tables fail rather than leaving you with an empty backup you believe is good.
+
+On an interactive terminal, omitting `--passphrase` for a `.dtzx` path prompts for it with masked input, which keeps the secret out of your shell history. Non-interactive runs need the flag.
+
 **Path rules:**
-- Single table → path is the output file
+- Single table → path is the output file, with the extension appended if missing
 - Multiple tables → path is a directory, noorm creates `<table>.dt` per table
 
 ### Import from Files
diff --git a/docs/guide/deployment.md b/docs/guide/deployment.md
new file mode 100644
index 00000000..7693f03d
--- /dev/null
+++ b/docs/guide/deployment.md
@@ -0,0 +1,190 @@
+# Deploying an Application
+
+
+On your laptop, `createContext({ config: 'dev' })` works because two things are sitting on disk: an encrypted `.noorm/state/state.enc` holding your configs, and an identity keypair in `~/.noorm/`. Neither belongs in a production image. You do not want your team's staging credentials baked into a container, and you certainly do not want a developer's private key there.
+
+The good news is that noorm already runs without either. The mode CI uses — configuration from environment variables alone — is the same mode your application should use in production. This guide covers what changes between the laptop and the cluster.
+
+
+## Split the job in two
+
+Most deployment pain comes from treating "get the schema up to date" and "serve traffic" as one step. They have opposite requirements:
+
+|  | Schema delivery | Application runtime |
+|---|---|---|
+| **Runs** | Once per release | In every replica, continuously |
+| **Needs** | Write access, your `sql/` and `changes/` directories | A connection and nothing else |
+| **Scales** | Exactly one at a time | Horizontally, to N replicas |
+| **Surface** | `noorm run build`, `noorm change ff` | `createContext()` |
+
+Keep them apart and horizontal scaling is uneventful. Fold schema delivery into application boot and every new replica becomes a schema-mutating process racing its siblings.
+
+
+## Runtime: connect from the environment
+
+When no stored config is in play and `NOORM_CONNECTION_DIALECT` and `NOORM_CONNECTION_DATABASE` are both set, `createContext()` builds a config from the environment alone. No project directory, no identity, no state file: a missing `state.enc` resolves to empty state rather than an error, and nothing asks for a private key.
+
+```typescript
+import { createContext } from '@noormdev/sdk';
+import type { DB } from './schema';
+
+export const ctx = await createContext<DB>();
+
+await ctx.connect();
+```
+
+That is the whole runtime setup. The variables:
+
+| Variable | Required | Notes |
+|----------|----------|-------|
+| `NOORM_CONNECTION_DIALECT` | Yes | `postgres`, `mysql`, `sqlite`, or `mssql` |
+| `NOORM_CONNECTION_DATABASE` | Yes | Together with `DIALECT`, this is what triggers environment-only mode |
+| `NOORM_CONNECTION_HOST` | No | Defaults to `localhost` |
+| `NOORM_CONNECTION_PORT` | No | Defaults per dialect: `5432` / `3306` / `1433` |
+| `NOORM_CONNECTION_USER` | Usually | |
+| `NOORM_CONNECTION_PASSWORD` | Usually | Read from your secret store, never from the image |
+| `NOORM_CONNECTION_SSL` | No | |
+| `NOORM_CONNECTION_POOL_MIN` | No | Defaults to `0` |
+| `NOORM_CONNECTION_POOL_MAX` | No | Defaults to `10` |
+
+The resulting config is named `__env__`, which is what you will see in any error message it raises.
+
+Install the driver alongside the SDK — it is an optional peer dependency, so noorm does not pull it in for you:
+
+```bash
+npm install @noormdev/sdk kysely pg
+```
+
+
+## One context per process
+
+A context owns a connection pool. Create it once when the process starts, share it across requests, and close it on shutdown:
+
+```typescript
+const ctx = await createContext<DB>();
+
+await ctx.connect();
+
+process.on('SIGTERM', async () => {
+
+    await server.close();
+    await ctx.disconnect();
+    process.exit(0);
+});
+```
+
+Calling `createContext()` per request would open a fresh pool per request, which is the classic way to exhaust a database's connection limit under load.
+
+That limit is the number worth doing arithmetic on before you scale out. `NOORM_CONNECTION_POOL_MAX` is a **per-replica** ceiling, so your real demand is replicas × pool max. Twenty replicas at the default of 10 will try to open 200 backends — comfortably past a stock PostgreSQL's `max_connections` of 100. Either lower the per-replica pool or put PgBouncer in front:
+
+```bash
+NOORM_CONNECTION_POOL_MAX=4    # 20 replicas x 4 = 80 backends
+```
+
+
+## Give the runtime the access it actually needs
+
+Your application queries tables. It does not need to build schemas or apply changes, and a config that permits those operations is a wider blast radius than the job requires. Configs carry per-channel roles, and environment-only configs default to `user: admin` — full access.
+
+Narrow it:
+
+```bash
+NOORM_ACCESS_USER=viewer
+NOORM_ACCESS_AGENT=false
+```
+
+With those set, Kysely queries work exactly as before, but the management operations refuse:
+
+```
+ProtectedConfigError: Cannot run.build on config "__env__":
+"run:build" is not allowed on config "__env__" (role: viewer).
+```
+
+Set both variables or neither. The access object requires both channels, so setting only `NOORM_ACCESS_USER` fails config validation at startup rather than falling back to a default.
+
+This is defense in depth, not a substitute for database-level permissions. Grant the runtime's database user only the privileges it needs; the noorm role stops the SDK's own management surface, not hand-written SQL.
+
+See [Access Roles](/guide/environments/configs#access-roles) for what each role permits.
+
+
+## Schema delivery runs once, elsewhere
+
+Run `build` and `change ff` as a release step, an init container, or a Kubernetes `Job` — anywhere that runs exactly once per deploy, before the new replicas take traffic:
+
+```yaml
+- name: Apply schema
+  env:
+      NOORM_CONNECTION_DIALECT: postgres
+      NOORM_CONNECTION_HOST: ${{ secrets.DB_HOST }}
+      NOORM_CONNECTION_DATABASE: myapp
+      NOORM_CONNECTION_USER: ${{ secrets.DB_DEPLOY_USER }}
+      NOORM_CONNECTION_PASSWORD: ${{ secrets.DB_DEPLOY_PASSWORD }}
+  run: |
+      noorm run build
+      noorm change ff
+```
+
+noorm takes a database lock around change execution, so a second run cannot interleave with the first. It does not queue: the lock is acquired with `wait: false`, so the loser fails immediately with a lock error naming the holder. Treat that as a safety net, not a design. Fold schema delivery into application boot and the second replica to start does not wait its turn, it crashes.
+
+If your changes render vault-backed secrets, the deploy step needs an enrolled identity too. That flow is covered in [CI/CD Automation](/guide/automation/ci#prod-ci) and applies unchanged here.
+
+
+## Docker
+
+Nothing noorm-specific goes in the image. No `.noorm/`, no identity, no config:
+
+```dockerfile
+FROM node:22-slim
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --omit=dev
+COPY dist ./dist
+
+CMD ["node", "dist/server.js"]
+```
+
+Configuration arrives as environment variables at run time:
+
+```yaml
+services:
+    app:
+        image: myapp:latest
+        environment:
+            NOORM_CONNECTION_DIALECT: postgres
+            NOORM_CONNECTION_HOST: db
+            NOORM_CONNECTION_DATABASE: myapp
+            NOORM_CONNECTION_USER: app
+            NOORM_CONNECTION_PASSWORD: ${DB_PASSWORD}
+            NOORM_CONNECTION_POOL_MAX: 4
+            NOORM_ACCESS_USER: viewer
+            NOORM_ACCESS_AGENT: 'false'
+```
+
+The `sql/` and `changes/` directories only need to be present wherever schema delivery runs — the CI checkout, or a separate migration image. Your application image does not need them.
+
+
+## One process, one database
+
+Connection details come from the process environment, and `createContext()` reads that environment when it resolves. There is no `createContext({ host, user, password })` overload today, which has a consequence worth stating plainly: **in environment-only mode, a process serves one database.** (A process that does have a `state.enc` can hold several contexts at once, one per stored config, by passing `createContext({ config: 'name' })`. That route is not available here, because environment-only mode is what you get when there is no state file.)
+
+If you are tempted to reassign `process.env` between calls to reach a second database, don't. The environment is process-global while `createContext()` is asynchronous, so two concurrent calls interleave and the later assignment wins for both:
+
+```typescript
+// Broken — both contexts connect to tenant_b.
+await Promise.all([
+    forTenant('tenant_a'),
+    forTenant('tenant_b'),
+]);
+```
+
+For multi-tenant or shard-per-customer designs, run a process per database, or hold a long-lived context per tenant created serially at startup rather than per request.
+
+Single-database services — the overwhelming majority — are unaffected.
+
+
+## What's Next?
+
+- [CI/CD Automation](/guide/automation/ci) — pipelines, identity enrollment, vault-backed secrets
+- [Configs](/guide/environments/configs) — access roles and the full environment variable table
+- [SDK Reference](/reference/sdk) — the context API in full
diff --git a/docs/guide/environments/configs.md b/docs/guide/environments/configs.md
index ffb64acd..c0e05e7b 100644
--- a/docs/guide/environments/configs.md
+++ b/docs/guide/environments/configs.md
@@ -30,28 +30,28 @@ Press `c` to open the config menu, then `a` to add a new config.
 
 The setup wizard walks you through each field:
 
-1. **Name** - A short identifier like `dev`, `staging`, or `prod`. Use lowercase with hyphens.
+1. **Config Name** - A short identifier like `dev`, `staging`, or `prod`. Use lowercase with hyphens.
 
-2. **Type** - Choose `local` for your machine or `remote` for servers.
+2. **Database Type** - Your database engine: PostgreSQL, MySQL, SQLite, or SQL Server.
 
-3. **Dialect** - Your database engine: `postgres`, `mysql`, `sqlite`, or `mssql`.
+3. **Host** - The server address. For local databases, this is usually `localhost`. SQLite doesn't need a host.
 
-4. **Host** - The server address. For local databases, this is usually `localhost`. SQLite doesn't need a host.
+4. **Port** - The port number. noorm fills in the default for your dialect (PostgreSQL: 5432, MySQL: 3306, MSSQL: 1433).
 
-5. **Port** - The port number. noorm fills in the default for your dialect (PostgreSQL: 5432, MySQL: 3306, MSSQL: 1433).
+5. **Database** - The database name, or file path for SQLite.
 
-6. **Database** - The database name, or file path for SQLite.
+6. **Username** and **Password** - Your credentials. Passwords are stored encrypted.
 
-7. **User** and **Password** - Your credentials. Passwords are stored encrypted.
+7. **User Role** and **Agent Role** - Who may do what through this config. See [Access Roles](#access-roles) below.
 
-8. **Paths** - Where your schema and change files live.
+8. **Test Database** - Marks the config as a test target, which build rules and the SDK's `requireTest` guard read.
 
-After completing the wizard, noorm validates the connection. If it succeeds, your config is saved.
+Before saving, noorm connects to the server to check the credentials. It uses the dialect's system database, so the target database does not have to exist yet. Schema and change directories are not part of a config: they come from `paths` in `settings.yml`.
 
 
 ## Creating a Config Non-Interactively
 
-`noorm config add` and `edit` launch the TUI wizard — they exist to guide credential entry interactively. Removal is the exception: `noorm config rm <name> --yes` deletes headlessly, no wizard involved (see the [CLI Reference](/headless#config-rm-name)). For CI/CD pipelines and scripts that need to skip the config wizard entirely, build the config from **environment variables** instead:
+`noorm config add` and `edit` do not run headlessly. They print the interactive-only message and exit non-zero, because credential entry and the connection test belong in the wizard. Two commands are the exception: `noorm config rm <name> --yes` deletes headlessly (see the [CLI Reference](/headless#config-rm-name)), and `noorm config import <file>` creates or replaces a config from JSON. For CI/CD pipelines and scripts that need to skip the config wizard entirely, build the config from **environment variables** instead:
 
 ```bash
 export NOORM_CONNECTION_DIALECT=postgres
@@ -72,7 +72,7 @@ When at least `NOORM_CONNECTION_DIALECT` and `NOORM_CONNECTION_DATABASE` are set
 
 Only one config is active at a time. All commands use the active config unless you specify otherwise.
 
-**In the TUI:** Press `c` for configs, select one from the list, then press `u` to use it.
+**In the TUI:** Press `c` for configs, highlight one in the list, then press `Enter` to activate it.
 
 **From the command line:**
 
@@ -86,13 +86,13 @@ noorm config use staging
 noorm -c prod run build
 ```
 
-The active config shows with a dot in listings:
+`noorm config list` marks the active one and tags anything whose access is no longer the default:
 
 ```
-Configs
-  * dev        sqlite   ./data/dev.db
-    staging    postgres db.staging.example.com
-    prod       postgres db.prod.example.com
+Configurations:
+  dev (active) — sqlite/./data/dev.db
+  staging — postgres/staging_db
+  prod — postgres/prod_db [user:operator agent:off]
 ```
 
 
@@ -117,6 +117,8 @@ Every config has these fields:
 | `pool` | No | Connection pool settings |
 | `identity` | No | Override the audit identity |
 
+Connection details nest under a `connection` object in the stored JSON, so `host` is `connection.host` and `ssl` is `connection.ssl`. `name`, `type`, `isTest`, `access`, and `identity` sit at the top level.
+
 **Default ports by dialect:**
 
 | Dialect | Default Port |
@@ -135,19 +137,28 @@ The channel is the caller, not the transport. An agent reaches noorm over MCP or
 
 | Role | Behavior |
 |------|----------|
-| `viewer` | Read-only: explore schema, run `SELECT`/`EXPLAIN` |
-| `operator` | Reads plus writes; destructive operations (`change run/ff/revert`, `run build`, `db create`/`db reset`) require typing a confirmation phrase; `db drop` is denied |
-| `admin` | Frictionless — everything allowed, nothing prompts |
+| `viewer` | Read-only: explore schema, run `SELECT`/`EXPLAIN`. Cannot read secrets |
+| `operator` | Reads plus writes; migrations, builds, and `db create`/`db reset` require typing a confirmation phrase; raw DDL, `db drop`, and `db teardown` are denied |
+| `admin` | Everything is permitted, but the operations that cannot be walked back still prompt |
 
 | Operation | viewer | operator | admin |
 |-----------|--------|----------|-------|
+| `db explore`, `SELECT` / `EXPLAIN` | allowed | allowed | allowed |
+| Raw `INSERT` / `UPDATE` / `DELETE` | denied | allowed | allowed |
+| Raw DDL (`CREATE` / `ALTER` / `DROP`) | denied | denied | allowed |
 | `change run` / `change ff` / `change revert` | denied | confirm | allowed |
-| `run build` | denied | confirm | allowed |
-| `db create` | denied | confirm | allowed |
-| `db teardown` | denied | confirm | allowed |
-| `db drop` | denied | denied | confirm |
+| `run build` / `run file` / `run dir` | denied | confirm | allowed |
+| `db create` / `db reset` | denied | confirm | allowed |
+| `db truncate` | denied | confirm | confirm |
+| `db drop` / `db teardown` | denied | denied | confirm |
+| `change rm`, `config rm`, overwriting a config | denied | confirm | confirm |
+| Reading vault or local secrets | denied | allowed | allowed |
+| Writing vault or local secrets | denied | confirm | allowed |
+| `vault propagate` | denied | confirm | confirm |
+
+`admin` is not a bypass. Dropping a database, tearing down a schema, truncating tables, removing a change or a config, overwriting a config's access roles, and propagating the vault key all confirm at every role that is allowed to attempt them. The full matrix lives in `src/core/policy/matrix.ts`.
 
-When an `operator`-role operation needs confirmation in the TUI, noorm asks you to type a phrase (`yes-<config-name>`). This catches the "oops, wrong database" moment before damage happens.
+When an operation needs confirmation in the TUI, noorm asks you to type a phrase (`yes-<config-name>`). This catches the "oops, wrong database" moment before damage happens.
 
 **Skipping confirmations in CI:**
 
@@ -170,6 +181,8 @@ noorm resolves the channel from the environment it was started in, in this order
 
 `TERM_PROGRAM`, `CI`, and whether stdout is a TTY are deliberately ignored: they describe the terminal or the pipeline, not the caller, and keying on them would lock a human out of their own CLI.
 
+`noorm mcp serve` sits above this chain. It declares `agent` outright, so stdio traffic stays on the agent channel even under `NOORM_CHANNEL=user`.
+
 Set `NOORM_CHANNEL=user` when *you* are scripting from inside an agent session and want your own role:
 
 ```bash
@@ -197,13 +210,15 @@ Environment variables override stored config values. This is how you inject secr
 | `NOORM_CONNECTION_PASSWORD` | `connection.password` |
 | `NOORM_CONNECTION_SSL` | `connection.ssl` |
 
-**Path variables:**
+**Path variables.** These two override `settings.yml`, not the config, because schema and change directories are project-wide:
 
-| Variable | Config Path |
-|----------|-------------|
+| Variable | Settings Path |
+|----------|---------------|
 | `NOORM_PATHS_SQL` | `paths.sql` |
 | `NOORM_PATHS_CHANGES` | `paths.changes` |
 
+The overlay stays out of the file itself. noorm never writes an ambient `NOORM_*` value back into `settings.yml`, which is version controlled.
+
 **Behavior variables:**
 
 | Variable | Purpose |
@@ -238,7 +253,7 @@ noorm run build  # Uses env-only config
 
 ## Validating Connections
 
-Before running changes, verify your config connects successfully. In the TUI, select a config and press `v` to run a full validation:
+Before running changes, verify your config connects successfully. In the TUI, highlight a config, press `+` for More, then press `v` to run a full validation:
 
 1. Can noorm connect with the provided credentials?
 2. Does the target database exist?
@@ -251,11 +266,11 @@ For headless smoke checks, run any command that opens a connection — e.g. `noo
 
 ## Exporting and Importing Configs
 
-You can export configs to share across team members or machines.
+There are two export paths, and they produce different files.
 
-**TUI:** `noorm ui` → Config → press `x` to export the highlighted config or `i` to import one.
+**TUI, for sharing with a teammate:** `noorm ui` → Config → `+` for More → `x` exports the highlighted config, `i` imports one. This path encrypts the config and its local secrets for a single recipient, using an ephemeral X25519 key exchange and AES-256-GCM, and writes `<name>.noorm.enc`. It leaves `user` and `password` out on purpose, so the recipient connects with their own credentials. You need the recipient's identity locally before you can export to them, and only their private key can decrypt the file. On import, noorm decrypts with your private key and prompts for your database credentials.
 
-**CLI:**
+**CLI, for backup and cross-machine transfer:** `noorm config export` writes plain JSON, and that JSON carries the connection password. Treat the file as a credential. noorm writes it with `0600` permissions and requires a role that can read secrets, so a `viewer` is refused.
 
 ```bash
 # Export to stdout or file
@@ -264,25 +279,28 @@ noorm config export dev --output ./dev-config.json
 
 # Import from file
 noorm config import ./dev-config.json
-noorm config import ./staging-config.json --force   # overwrite existing
+noorm config import ./staging-config.json --force --yes   # overwrite existing
 ```
 
-Exports strip passwords and other sensitive fields. The exported JSON looks like this:
+The exported JSON looks like this:
 
 ```json
 {
     "name": "dev",
     "type": "local",
-    "dialect": "sqlite",
-    "database": "./data/dev.db",
-    "paths": {
-        "schema": "./sql",
-        "changes": "./changes"
+    "isTest": false,
+    "access": {
+        "user": "admin",
+        "agent": "viewer"
+    },
+    "connection": {
+        "dialect": "sqlite",
+        "database": "./data/dev.db"
     }
 }
 ```
 
-After importing, set passwords or secrets separately: through the TUI's edit screen or with `NOORM_CONNECTION_PASSWORD` at command time.
+Overwriting an existing config rewrites its access roles, so `--force` on its own is not enough: `config import` also wants `--yes` (or `NOORM_YES`) to confirm. When you import a file that has no credentials in it, set the password afterward through the TUI's edit screen or with `NOORM_CONNECTION_PASSWORD` at command time.
 
 
 ## Managing Configs from the CLI
@@ -314,9 +332,9 @@ noorm config import ./backup.json
 ### Setting Up a New Developer
 
 1. Clone the repository
-2. Run `noorm ui` and import the shared config template under Config → `i`
+2. Run `noorm ui` and import the shared config under Config → `+` → `i`
 3. Edit the imported config and set the password (Config → highlight → `e`)
-4. Press `v` on the same screen to validate the connection
+4. Back on the config list, press `+` then `v` to validate the connection
 
 
 ### CI/CD Pipeline
diff --git a/docs/guide/environments/secrets.md b/docs/guide/environments/secrets.md
index ee6a7b3d..a5293548 100644
--- a/docs/guide/environments/secrets.md
+++ b/docs/guide/environments/secrets.md
@@ -22,7 +22,9 @@ Secrets integrate directly with SQL templates, so you can reference them without
 
 You can manage local secrets through the TUI (masked input, nothing in shell history) or the CLI.
 
-**TUI:** Launch `noorm ui`, press `s` for Settings → Secrets. The form masks password input, validates connection strings as URIs, and writes the encrypted result to `.noorm/state/state.enc`. The same screen lists secrets for the active config: which are set, which are missing, and their declared types. Values stay hidden.
+**TUI:** Launch `noorm ui`, press `c` for configs, highlight a config, and press `k` for its secrets. The list groups required secrets (declared in `settings.yml`) above optional ones and shows which are set, which are missing, and their declared types. Values stay hidden. Press `a` to add one; the form masks `password` and `api_key` input, validates `connection_string` values as URIs, and writes the encrypted result to `.noorm/state/state.enc`.
+
+Settings → Secrets is a different screen. It edits the secret *declarations* in `settings.yml` (key, type, description, required), not the encrypted values.
 
 **CLI:** The `noorm secret` namespace manages config-scoped local secrets headlessly:
 
@@ -157,8 +159,8 @@ The local secret store exists for per-developer overrides — `noorm secret set`
 # Write a secret to the vault
 noorm vault set DB_PASSWORD "$DB_PASSWORD"
 
-# Pipe a secret to avoid process listings
-echo "$DB_PASSWORD" | noorm vault set DB_PASSWORD
+# Pipe a secret to keep it out of the process table and shell history
+echo "$DB_PASSWORD" | noorm vault set DB_PASSWORD --stdin
 
 # List vault secrets as JSON
 noorm vault list --json
@@ -182,15 +184,15 @@ noorm takes several measures to protect your secrets:
 6. **Automatic redaction** - The logger masks secret fields if they appear in event data
 
 ::: warning Don't Commit state.enc
-Add `.noorm/state/state.enc` to your `.gitignore`. The file is encrypted with machine-specific keys and won't work on other machines.
+Add `.noorm/state/state.enc` to your `.gitignore`. Its encryption key is derived from your private identity key in `~/.noorm/identity.key`, so nobody else can read the file, and neither can you on a machine that does not have that key.
 :::
 
 
 ## Deleting Secrets
 
-Remove optional local secrets through the TUI: `noorm ui` → Settings → Secrets → highlight the entry and press `d`. For team-shared values stored in the vault, use `noorm vault rm <KEY>`.
+Remove a local secret through the TUI: Config → highlight the config → `k` → highlight the entry and press `d`. Headlessly, `noorm secret rm <KEY> --yes`. For team-shared values stored in the vault, use `noorm vault rm <KEY>`.
 
-Required secrets (those declared in `settings.yml`) cannot be deleted, only updated. The TUI tells you whether a secret is universal or stage-specific when you try to delete a required one.
+A required secret (one declared in `settings.yml`) cannot be deleted outright, only updated. The exception is a required secret that also exists in the vault: deleting the local copy is allowed there, because the vault value takes over. To retire the requirement itself, edit `settings.yml`.
 
 
 ## What's Next?
diff --git a/docs/guide/environments/stages.md b/docs/guide/environments/stages.md
index 7b86a0f7..f2d4b618 100644
--- a/docs/guide/environments/stages.md
+++ b/docs/guide/environments/stages.md
@@ -16,7 +16,7 @@ Stages solve this. They're templates defined in your project's `settings.yml` th
 
 ## What Stages Are
 
-A **stage** is a named template for database configs. When you create a config and assign it to a stage, the config inherits the stage's defaults and requirements.
+A **stage** is a named template for database configs. A config whose name matches a stage inherits that stage's defaults and requirements.
 
 Think of stages as blueprints:
 
@@ -60,10 +60,10 @@ stages:
             protected: true
 ```
 
-When a developer creates a config from the `staging` stage, it automatically:
-- Uses postgres dialect
-- Is not protected (staging data is expendable)
-- Requires a `STRIPE_TEST_KEY` secret before builds can run
+A config named `staging` then automatically:
+- Defaults to the postgres dialect
+- Keeps its own access roles, with no ceiling applied (staging data is expendable)
+- Declares `STRIPE_TEST_KEY` as required, so the TUI lists it as missing until it is set and any template that reads it fails until then
 
 
 ## Stage Properties
@@ -97,10 +97,11 @@ Some defaults are **enforced** and cannot be overridden in the TUI:
 | Default | Behavior |
 |---------|----------|
 | `protected: true` | Acts as an access ceiling: whatever `access` the config or the developer sets, the *resolved* access is clamped to at most `{ user: 'operator', agent: 'viewer' }` |
-| `isTest: true` | Cannot be set to false in the TUI |
-| `dialect` | Cannot be changed after config creation |
+| `dialect` | Cannot be changed after config creation. The TUI edit screen shows it read-only |
 
-This means if your `prod` stage sets `protected: true`, developers cannot create a fully-open production config through the normal workflow — even picking `admin` in the TUI's access editor gets clamped back down at resolution time.
+This means if your `prod` stage sets `protected: true`, developers cannot create a fully-open production config through the normal workflow. Even picking `admin` in the TUI's access editor gets clamped back down at resolution time.
+
+`isTest` is a seed value, not a ceiling. A stage that sets `isTest: true` supplies the default, but a stored config's own `isTest` wins at resolution, and the TUI edit screen lets a developer uncheck it.
 
 ::: tip Manual Override
 The ceiling is enforced every time the config is resolved, so it survives even a manually edited state file — there's no stored value to hand-edit around. The protection is against accidents, not an attempt at real security.
@@ -119,21 +120,14 @@ stages:
             protected: true
 ```
 
-A locked production config cannot be accidentally removed. The developer must first change the config's stage assignment.
+A locked production config cannot be accidentally removed. Deletion stays blocked until someone edits `settings.yml` or the config stops matching the stage name.
 
 
 ## Assigning a Config to a Stage
 
-When you create a new config in the TUI, noorm asks which stage to use:
-
-```
-? Select stage for new config:
-  dev        Local development database
-  staging    Staging environment
-  prod       Production database
-```
+There is no stage picker. A config links to a stage when their names match: a config named `prod` picks up the `prod` stage's defaults, secrets, and lock. Name your configs after your stages and the link happens on its own.
 
-The config inherits that stage's defaults. The stage selection happens during config creation through the TUI.
+`settings.yml` is the only place that link is defined, so a config's stage is not stored on the config and cannot drift per developer. The SDK can override the lookup with `createContext({ stage: 'prod' })` when a config's name does not match the stage you want.
 
 
 ## Stage-Specific Secrets
@@ -164,9 +158,9 @@ Secret types control how the TUI handles input:
 | `api_key` | Masked input, no echo |
 | `connection_string` | Plain text, URI validation |
 
-**Required secrets** must be set before builds can run. If a template references a missing required secret, the build fails with a clear error.
+**Required secrets** show as missing in the TUI secret list until you set them, and the enforcement point is the template render. Reading `$.secrets.STRIPE_TEST_KEY` when nothing resolved it throws `Secret "STRIPE_TEST_KEY" not found (searched: config-local, global-local, vault)` and the build stops. It never renders as the literal text `undefined`.
 
-**Optional secrets** are prompted but can be skipped. Templates that reference them should handle the undefined case.
+**Optional secrets** work the same way at render time, so a template that may run without one should probe first with `{% if ('DEBUG_KEY' in $.secrets) { %}`. The `in` check does not throw.
 
 
 ### Universal Secrets
diff --git a/docs/guide/environments/vault.md b/docs/guide/environments/vault.md
index eb9b34d8..36c1d728 100644
--- a/docs/guide/environments/vault.md
+++ b/docs/guide/environments/vault.md
@@ -20,7 +20,7 @@ When a template references `secrets.API_KEY`, noorm checks three sources in orde
 ├─────────────────────────────────────────────────────────────┤
 │  3. Vault secret                          (lowest priority) │
 │     Team-shared value from the database                     │
-│     Location: __noorm_vault__ table                         │
+│     Location: the vault table                               │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -35,7 +35,7 @@ Your team stores the production Stripe key in the vault:
 Vault:  STRIPE_KEY = "sk_live_abc123..."
 ```
 
-For local development, you want to use Stripe's test mode. Set a local override through the TUI — `noorm ui` → Settings → Secrets → `a`, with key `STRIPE_KEY` and value `sk_test_xyz789...`. Local secrets are stored encrypted in your `.noorm/state/state.enc` and never leave your machine.
+For local development, you want to use Stripe's test mode. Set a local override through the TUI: `noorm ui` → Config → highlight the config → `k` → `a`, with key `STRIPE_KEY` and value `sk_test_xyz789...`. Headlessly, `noorm secret set STRIPE_KEY "sk_test_xyz789..."`. Local secrets are stored encrypted in your `.noorm/state/state.enc` and never leave your machine.
 
 Now when templates reference `secrets.STRIPE_KEY`:
 
@@ -79,7 +79,7 @@ Individual secrets are encrypted with the shared vault key:
 
 - AES-256-GCM authenticated encryption
 - Random IV per secret
-- Stored as JSON in `__noorm_vault__` table
+- Stored as JSON in the vault table
 
 This design means: compromising the database alone doesn't expose secrets. An attacker needs both database access AND a team member's private key.
 
@@ -118,13 +118,15 @@ noorm vault list
 noorm vault rm OLD_API_KEY
 ```
 
-The TUI provides a visual interface at **Secrets** (`k` from home):
+The TUI provides a visual interface at **Vault** (`v` from home):
 
-- View all vault secrets with who set them
-- Add, edit, and delete secrets
+- View all vault secrets, each labeled with who set it
+- Add a secret with `a`, edit one by selecting it
 - See pending users who need access
 - One-key propagation (`p`)
 
+Removing a vault secret is CLI-only: `noorm vault rm <KEY>`.
+
 
 ## Granting Team Access
 
@@ -136,33 +138,32 @@ noorm vault propagate
 
 This encrypts the vault key for each pending user's public key. After propagation, they can decrypt vault secrets on their next connection.
 
-The TUI shows a badge when users are pending:
+The Vault screen counts them in its header:
 
 ```
-Vault  [2 pending]
+3 secret(s) | 4 user(s) with access   (2 pending)
 ```
 
-Press `p` to propagate immediately.
+Press `p` there to propagate. noorm lists the recipients it is about to grant access to and asks you to confirm before it writes anything.
 
 
 ## Copying Secrets Between Configs
 
-Move secrets from one database to another:
+Move a secret from one database to another. `vault cp` takes three positional arguments in this order: the key, the source config, and the destination config. All three are required, so copy one key per invocation.
 
 ```bash
-# Copy specific secret
+# Copy one secret
 noorm vault cp API_KEY staging production
 
-# Copy all secrets
-noorm vault cp staging production
-
-# Force overwrite existing
-noorm vault cp --force staging production
+# Overwrite a key that already exists on the destination
+noorm vault cp API_KEY staging production --force
 
-# Preview without executing
-noorm vault cp --dry-run staging production
+# Preview without writing
+noorm vault cp API_KEY staging production --dry-run
 ```
 
+A dry run performs the same preflight as a real copy (vault access on both ends, source key exists, destination collisions) and only skips the write.
+
 If the destination vault isn't initialized, noorm initializes it automatically using your identity.
 
 
@@ -174,7 +175,7 @@ Vault secrets merge into the template context alongside local secrets:
 -- sql/setup/external-api.sql.tmpl
 -- Vault secret (or local override if set)
 INSERT INTO api_config (provider, key)
-VALUES ('stripe', '<%= secrets.STRIPE_KEY %>');
+VALUES ('stripe', {%~ $.quote($.secrets.STRIPE_KEY) %});
 ```
 
 The resolution order means you can:
@@ -198,14 +199,14 @@ noorm vault set API_KEY "$API_KEY"
 # List with JSON output
 noorm vault list --json
 
-# Copy secrets between environments
-noorm vault cp --all staging production
+# Copy a secret between environments
+noorm vault cp API_KEY staging production
 ```
 
-Pipe values to avoid command history:
+Pipe the value in with `--stdin` to keep it out of the process table, shell history, and `set -x` traces:
 
 ```bash
-echo "$SECRET_VALUE" | noorm vault set MY_SECRET
+echo "$SECRET_VALUE" | noorm vault set MY_SECRET --stdin
 ```
 
 
@@ -215,7 +216,7 @@ The vault design provides several security properties:
 
 1. **End-to-end encryption** - Secrets encrypted in memory, transmitted encrypted, stored encrypted
 2. **Zero-knowledge database** - Database administrators see only ciphertext
-3. **Key rotation via propagation** - Each user has unique ciphertext for the same vault key
+3. **Per-user key distribution** - Propagation re-encrypts the same vault key for each recipient, so every user holds unique ciphertext
 4. **No shared secrets in transit** - ECDH derives keys without transmitting them
 5. **Authenticated encryption** - AES-256-GCM detects tampering
 
@@ -228,9 +229,9 @@ Limitations to understand:
 
 ## Database Schema
 
-The vault uses two database structures:
+The vault uses two database structures. Their names depend on the dialect: PostgreSQL and SQL Server put noorm's tracking tables in a dedicated `noorm` schema (`noorm.vault`, `noorm.identities`), while MySQL and SQLite have no schemas and keep the prefixed forms (`__noorm_vault__`, `__noorm_identities__`) in the default schema.
 
-**`__noorm_vault__` table:**
+**The vault table:**
 
 | Column | Type | Description |
 |--------|------|-------------|
@@ -241,7 +242,7 @@ The vault uses two database structures:
 | `created_at` | timestamp | Creation time |
 | `updated_at` | timestamp | Last update time |
 
-**`__noorm_identities__` extension:**
+**The identities table extension:**
 
 | Column | Type | Description |
 |--------|------|-------------|
@@ -253,5 +254,5 @@ A null `encrypted_vault_key` means the user is pending vault access.
 ## What's Next?
 
 - [Secrets](/guide/environments/secrets) - Local secret storage
-- [Identity](/dev/identity) - Cryptographic identity setup
+- [Identity](/cli/identity) - The keypair that lets teammates encrypt secrets to you
 - [Templates](/guide/sql-files/templates) - Using secrets in dynamic SQL
diff --git a/docs/guide/sql-files/execution.md b/docs/guide/sql-files/execution.md
index df723bf3..a79b72fd 100644
--- a/docs/guide/sql-files/execution.md
+++ b/docs/guide/sql-files/execution.md
@@ -9,7 +9,7 @@ Here's what happens under the hood:
 
 1. noorm computes a SHA-256 checksum of the SQL that will actually run — for a `.sql.tmpl`, that is the *rendered* output, not the file on disk
 2. It checks the tracking database for a previous execution record
-3. If the file is new, changed, or previously failed, it runs
+3. If the file is new, changed, previously failed, or belonged to an operation a teardown marked stale, it runs
 4. If unchanged and successful, it's skipped
 5. After execution, the result and new checksum are recorded
 
@@ -39,19 +39,18 @@ sql/
     └── 001_active_users.sql      # Runs last
 ```
 
-Output shows what ran and what was skipped:
+Output shows what ran and what was skipped. Every line carries a timestamp and a level marker ahead of the message:
 
 ```
-Building schema...
-
-✓ sql/01_tables/001_users.sql
-• sql/01_tables/002_posts.sql (unchanged)
-✓ sql/02_views/001_active_users.sql
-
-Executed: 2
-Skipped:  1
+Starting schema build (3 files)
+Executed sql/01_tables/001_users.sql (14ms)
+Skipped sql/01_tables/002_posts.sql (unchanged)
+Executed sql/02_views/001_active_users.sql (9ms)
+Build complete: 2 run, 1 skipped (412ms)
 ```
 
+Add `--json` to get the same events as newline-delimited JSON on stderr and the batch result on stdout.
+
 
 ## run file
 
@@ -108,7 +107,11 @@ sql/02_views/001_my_view.sql  →   tmp/sql/02_views/001_my_view.sql
 sql/03_seeds/001_users.sql.tmpl  →   tmp/sql/03_seeds/001_users.sql
 ```
 
-Templates are fully rendered with your current config context. The `.tmpl` extension is stripped from output files.
+Templates are fully rendered with your current config context. The `.tmpl` extension is stripped from output files. Nothing is written to the database and nothing is tracked.
+
+::: warning Dry run output contains your secrets
+Rendering resolves every secret the template reads, in plaintext, into the files under `tmp/`. noorm writes them owner-only (`0600`, in `0700` directories), but `noorm init` does not add `tmp/` to `.gitignore`. Add it yourself, and delete the output when you're done reading it.
+:::
 
 **When to use dry run:**
 
@@ -116,35 +119,37 @@ Templates are fully rendered with your current config context. The `.tmpl` exten
 |----------|---------|
 | Inspect rendered templates | `noorm run build --dry-run` |
 | Review before production deploy | `noorm run build --dry-run -c production` |
-| Debug template variables | `noorm run file seed.sql.tmpl --dry-run` |
+| Debug one template | `noorm run preview seed.sql.tmpl` |
 | CI/CD validation step | `noorm run build --dry-run` |
 
 
 ## What Gets Tracked
 
-noorm maintains two tables in your database to track execution history:
+noorm maintains two tables in your database to track execution history. On PostgreSQL and SQL Server they live in a dedicated `noorm` schema; MySQL and SQLite have no schemas, so they keep prefixed names in the default schema.
 
-**`__noorm_change__`** - Operation records:
+**`noorm.change`** (`__noorm_change__` on MySQL and SQLite) - Operation records:
 
 | Field | Description |
 |-------|-------------|
-| `name` | Operation identifier (e.g., `build:2024-01-15T10:30:00`) |
-| `change_type` | `'build'` or `'run'` |
+| `name` | Operation identifier (e.g., `build:2024-01-15T10:30:00.000Z`) |
+| `change_type` | `'build'`, `'run'`, or `'change'` |
 | `executed_by` | Identity string (who ran it) |
 | `config_name` | Which config was used |
-| `status` | `'pending'`, `'success'`, `'failed'` |
+| `status` | `'pending'`, `'success'`, `'failed'`, `'reverted'`, `'stale'` |
 
-**`__noorm_executions__`** - Individual file records:
+**`noorm.executions`** (`__noorm_executions__` on MySQL and SQLite) - Individual file records:
 
 | Field | Description |
 |-------|-------------|
 | `change_id` | FK to parent operation |
-| `filepath` | File that was executed |
-| `checksum` | SHA-256 of file contents |
-| `status` | `'success'`, `'failed'`, `'skipped'` |
-| `skip_reason` | `'unchanged'` if skipped |
+| `filepath` | File that was executed, relative to the project root |
+| `checksum` | SHA-256 of the SQL that actually ran (the rendered output for a `.sql.tmpl`) |
+| `status` | `'pending'`, `'success'`, `'failed'`, `'skipped'` |
+| `skip_reason` | `'unchanged'` when change detection skipped it, or `Skipped: failure in <file>` when an earlier file in the batch failed |
 | `duration_ms` | Execution time |
 
+Every file in a batch gets a `'pending'` row before the first one executes, so an interrupted build still shows you what it was going to do. Rows move to their final status as the run proceeds.
+
 These tables let noorm answer: "Has this exact file content been executed before, and did it succeed?"
 
 
@@ -239,7 +244,7 @@ For the gory details on what the runner does under the hood, see [MSSQL Batch Ha
 | `noorm run file <path>` | Execute single file |
 | `noorm run dir <path>` | Execute files in directory |
 | `--force` | Re-run regardless of changes |
-| `--dry-run` | Preview without executing |
+| `--dry-run` | Render to `tmp/` without executing (`run build`, `run dir`) |
 
 The checksum system means you can run `noorm run build` as often as you want—only changed or new files execute. This is the foundation of noorm's approach to database schema management.
 
diff --git a/docs/guide/sql-files/organization.md b/docs/guide/sql-files/organization.md
index d8d16520..c09aa5cc 100644
--- a/docs/guide/sql-files/organization.md
+++ b/docs/guide/sql-files/organization.md
@@ -88,10 +88,11 @@ seeds/
 
 ## Execution Order
 
-noorm processes files in **alphabetical order by full path**. This is the critical rule for understanding how your schema executes. This means:
+noorm walks your schema directory recursively, collects every `.sql` and `.sql.tmpl` file, and sorts the **full paths as strings**. That sorted list is the execution order. This is the critical rule for understanding how your schema executes. It means:
 
-1. Folders are sorted first
-2. Files within each folder are sorted second
+1. The directory part of the path decides the order first
+2. File names break ties inside the same directory
+3. The comparison is by character code, not dictionary order, so every uppercase letter sorts before every lowercase one: `Users.sql` runs before `accounts.sql`
 
 Without numeric folder prefixes, alphabetical order causes problems:
 
@@ -143,10 +144,19 @@ build:
 
 Folder names are relative to your `paths.sql` directory, not the project root. With the default `paths.sql: ./sql`, an entry of `01_tables` means `./sql/01_tables` — so you do **not** repeat the `sql/` prefix.
 
-::: warning A wrong include path fails silently
-`sql/01_tables` resolves to `./sql/sql/01_tables` and matches nothing. noorm does not treat that as an error: the build reports success, runs zero files, and exits `0`, leaving your schema uncreated until something downstream fails on a missing table.
+::: warning A wrong include path still exits 0
+`sql/01_tables` resolves to `./sql/sql/01_tables` and matches nothing. `noorm run build` names the offending entries in a warning:
 
-If `noorm run build` reports success but ran zero files, an include entry is almost certainly the cause. A leading `./` or trailing `/` matches nothing for the same reason.
+```
+Ignored 1 build.include entry that matched no files: sql/01_tables
+Include paths are relative to paths.sql — use `01_tables`, not `sql/01_tables`.
+```
+
+The build still reports success and exits `0`, so a pipeline that only checks the exit code will not catch it. Read the warnings.
+
+A mistyped `exclude` entry gets the same treatment and is the more dangerous half: nothing is excluded, so the files you meant to fence off run against the target database.
+
+A leading `./` or a trailing `/` matches nothing for the same reason.
 :::
 
 The `include` array is a **filter**—it controls which folders are included, not their order. Execution order is always alphanumeric. Use numeric prefixes to control the sequence:
@@ -188,6 +198,12 @@ This means:
 - CI builds skip slow seed files
 - Development gets everything
 
+::: warning A rule `include` narrows the whole build
+An empty `build.include` means "every folder under `paths.sql`". A matching rule does not add to that set, it replaces it: its `include` entries are merged into `build.include`, and the moment that list is non-empty only the listed folders run.
+
+So on a project with no `build.include`, the rule above turns a test build into `04_seeds` and `05_test-fixtures` only. Your tables never get created. If you use rule `include` at all, list every folder you want in `build.include` too, and use rule `exclude` for the conditional part.
+:::
+
 
 ## Organizing by Feature vs by Type
 
diff --git a/docs/guide/sql-files/templates.md b/docs/guide/sql-files/templates.md
index d7343a4a..ed2a8e68 100644
--- a/docs/guide/sql-files/templates.md
+++ b/docs/guide/sql-files/templates.md
@@ -21,8 +21,11 @@ Templates use [Eta](https://eta.js.org/) with custom delimiters designed to avoi
 |--------|---------|---------|
 | `{% %}` | JavaScript code block | `{% for (const x of $.items) { %}` |
 | `{%~ %}` | Output a value | `{%~ user.name %}` |
+| `-- {% %}` | Code block on a line of its own, disguised as a SQL comment | `-- {% for (const x of $.items) { %}` |
 | `$` | Context variable | `$.config`, `$.secrets`, `$.uuid()` |
 
+A line whose entire content is `-- {% ... %}` gets its `-- ` prefix and its newline stripped before Eta parses the file, so the directive produces no output. Writing loops and conditionals that way keeps the `.sql.tmpl` file valid SQL, which means your editor still highlights it and a SQL linter still reads it. Inline tags and real `--` comments are untouched.
+
 Here's a simple example:
 
 ```sql
@@ -45,7 +48,7 @@ INSERT INTO roles (name) VALUES ('viewer');
 
 When noorm encounters a `.sql.tmpl` file:
 
-1. Scans the template's directory for data files (JSON, YAML, CSV)
+1. Scans the template's directory for data files (JSON5, YAML, CSV, `.dt`, and referenced JS/TS modules)
 2. Walks up the directory tree collecting `$helpers.ts` files
 3. Builds a context object (`$`) with helpers, data, config, and secrets
 4. Renders the template with Eta
@@ -63,7 +66,9 @@ Everything available in your template lives on the `$` object:
 | `$.config` | Active database configuration |
 | `$.secrets` | Decrypted secrets for active config |
 | `$.globalSecrets` | Decrypted global secrets |
-| `$.env` | Environment variables |
+| `$.env` | `process.env` |
+
+Data files win the name: a `config.json` or `config.yml` sitting beside the template claims the `config` key, and `$.config` then holds that file instead of the active database configuration. Helpers lose to data files the same way, so keep helper exports and data file base names distinct.
 
 
 ## Built-in Helpers
@@ -80,6 +85,8 @@ INSERT INTO users (name) VALUES ({%~ $.quote(user.name) %});
 -- Output: INSERT INTO users (name) VALUES ('O''Reilly');
 ```
 
+`null` renders as the SQL keyword `NULL`. `undefined` throws, because no rendering of it is correct and the old behavior wrote the literal six-character string `undefined` into the database. Pass `null` when you mean SQL `NULL`.
+
 ### $.escape(value)
 
 Escapes a string by doubling single quotes, without adding surrounding quotes:
@@ -130,6 +137,8 @@ Includes another SQL file. The path is relative to the current template:
 {%~ await $.include('../lib/audit_triggers.sql') %}
 ```
 
+An included `.sql` file is inserted verbatim. An included `.sql.tmpl` file is rendered first, with the same config and secrets, and its output is inserted.
+
 
 ## Auto-Loading Data Files
 
@@ -151,6 +160,23 @@ File names are converted to camelCase:
 | `seed_data.yml` | `$.seedData` |
 | `API_KEYS.json` | `$.apiKeys` |
 
+Subdirectories are not scanned, and neither are `.sql` files (those are for `$.include()`), dotfiles, `$helpers.*`, or other `.tmpl` files.
+
+
+### Executable Side-Cars Load Only When Referenced
+
+`.js`, `.mjs`, and `.ts` data files are an exception to auto-loading. Parsing a `.csv` cannot do anything, but importing a `.ts` runs whatever is in it. So noorm loads an executable side-car only when the template text actually names its key, as `$.key` or `$['key']`:
+
+```sql
+-- 001_seed.sql.tmpl, sitting next to build-rows.ts
+-- The mention of $.buildRows is what makes build-rows.ts load and run.
+{% for (const row of $.buildRows) { %}
+INSERT INTO rows (label) VALUES ({%~ $.quote(row.label) %});
+{% } %}
+```
+
+A `build-rows.ts` that no template mentions is skipped, including during `run preview`, `run inspect`, and `--dry-run`, the three commands whose whole point is not to act. The check is syntactic, so a key you reach some other way (a computed lookup, a helper that reads it) will not trigger the load. Reference it by name once and it works.
+
 
 ### Naming Collisions
 
@@ -468,7 +494,7 @@ Each fragment is plain SQL that could run on its own. The template just stitches
 
 **Secret Exposure**: The rendered SQL may contain sensitive values from `$.secrets`. Don't log rendered templates in production.
 
-**Code Execution**: `$helpers.ts` files and `.js` data files execute arbitrary code. Only use trusted sources.
+**Code Execution**: `$helpers.ts` files execute arbitrary code whenever a template in or under their directory renders. `.js`, `.mjs`, and `.ts` data files execute only when a template names their key. Both run in the noorm process with your environment. Only use trusted sources.
 
 **Path Traversal**: `$.include()` resolves relative paths and cannot escape the project root.
 
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 74f73fb0..1f7ea6ba 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -71,8 +71,10 @@ See [SDK reference — Parameter handling and NULL semantics](../reference/sdk.m
 ## `noorm sql "SELECT ..."` errors with "Unknown command"
 
 The bare `noorm sql "<SQL>"` form is supported, but only when the
-first token of the query is one of citty's recognized SQL keywords
-(`SELECT`, `INSERT`, `UPDATE`, `DELETE`, `WITH`, etc.). For anything
+first token of the query is one of the SQL verbs noorm rewrites on
+(`SELECT`, `INSERT`, `UPDATE`, `DELETE`, `WITH`, etc.). Citty resolves
+`sql`'s subcommands first, so noorm rewrites `sql <verb> …` to
+`sql query <verb> …` before citty ever sees it. For anything
 that starts with a leading comment, a CTE-style preamble, or a
 non-recognized verb, use the explicit subcommand:
 
@@ -83,12 +85,21 @@ See [`noorm sql`](../cli/sql.md) for the full list of recognized
 keywords and when each form fires.
 
 
-## `noorm change ff --dry-run` still commits
+## `noorm change ff --dry-run` wrote files I didn't expect
 
-Some commands accept `--dry-run` and some don't — `change ff` is one
-of the ones that doesn't (as of this writing). When you need a
-preview, use the SDK's `changes.apply(name, { dryRun: true })` or
-inspect rendered SQL via `noorm run preview <path>`.
+`change ff` does accept `--dry-run`, and it does not touch the
+database. What it does do is *render* every pending change to `tmp/`
+so you can read the SQL that would have run, including any secrets
+the templates resolved, in plaintext. `tmp/` is not gitignored by a
+project noorm scaffolds, so clean it up.
+
+    noorm change ff --dry-run
+    noorm run build --dry-run
+
+To render a single template without the change machinery, use
+`noorm run preview <path>`. From the SDK the same preview is
+`changes.apply(name, { dryRun: true })` or
+`changes.ff({ dryRun: true })`.
 
 
 ## `noorm init` errors in CI with "requires an interactive terminal"
diff --git a/docs/headless.md b/docs/headless.md
index 2d82eaa6..7d7dbd2d 100644
--- a/docs/headless.md
+++ b/docs/headless.md
@@ -22,7 +22,7 @@ noorm change --help          # Subcommands of `change`
 noorm change ff --help       # Args, options, and examples for `change ff`
 ```
 
-For shell completion, run `noorm complete` and follow the printed instructions for your shell.
+For shell completion, run `noorm complete <shell>` and source the script it prints. Supported shells: `zsh`, `bash`, `fish`, `powershell`, `fig`. A bare `noorm complete` is the runtime completion hook, not a generator, and errors without `--`.
 
 
 ## Global Flags
@@ -184,10 +184,16 @@ Each config carries a per-channel access grant: `access: { user, agent }`. The `
 | `sql` writes (INSERT/UPDATE/DELETE) | deny | allow | allow |
 | `sql` DDL (CREATE/ALTER/DROP/...) | deny | deny | allow |
 | `change run`/`ff`/`revert`, `run build`/`file`/`dir` | deny | confirm | allow |
-| `db create`, `db reset` (truncate/teardown/reset) | deny | confirm | allow |
+| `db create`, `db reset`, `db transfer --to` | deny | confirm | allow |
+| `db truncate` | deny | confirm | confirm |
+| `db teardown` | deny | deny | confirm |
 | `db drop` | deny | deny | confirm |
-| `config rm` | deny | confirm | confirm |
+| `config rm`, `config import --force` | deny | confirm | confirm |
 | `change rm` | deny | confirm | confirm |
+| `vault list`, `secret list`/`config export` | deny | allow | allow |
+| `vault set`/`rm`, `secret set`/`rm` | deny | confirm | allow |
+| `vault propagate` | deny | confirm | confirm |
+| `lock force` | deny | confirm | confirm |
 
 Raw SQL (`noorm sql`) is gated by what the statement actually does, not by a flag — a multi-statement input is classified by its highest class (a `SELECT` plus a `DROP` classifies as DDL). Unparseable or unrecognized statements classify as DDL, fail closed.
 
@@ -211,7 +217,7 @@ noorm init --force      # Reinitialize an existing .noorm/
 noorm init --yes        # Non-interactive, requires existing identity
 ```
 
-**TTY required by default.** Fails with exit code 1 in CI or when stdin is piped. For scripted bootstrap, set up the identity with `noorm identity init --name ... --email ...` then run `noorm init --yes` (or set `NOORM_YES=1`). For the full non-interactive matrix across all TTY-gated commands, see [Non-interactive operation](./guide/automation/non-interactive.md). For ephemeral CI runners, use `noorm ci init` instead.
+**TTY required by default.** Fails with exit code 2 (usage error) in CI or when stdin is piped. For scripted bootstrap, set up the identity with `noorm identity init --name ... --email ...` then run `noorm init --yes` (or set `NOORM_YES=1`). For the full non-interactive matrix across all TTY-gated commands, see [Non-interactive operation](./guide/automation/non-interactive.md). For ephemeral CI runners, use `noorm ci init` instead.
 
 
 ### Configuration
@@ -227,12 +233,17 @@ noorm config list --json
 
 **JSON output:**
 ```json
-[
-    {"name": "dev", "dialect": "postgres", "active": true},
-    {"name": "staging", "dialect": "postgres", "active": false}
-]
+{
+    "success": true,
+    "configs": [
+        {"name": "dev", "type": "local", "dialect": "postgres", "database": "app", "isActive": true, "isTest": false, "access": {"user": "admin", "agent": "viewer"}},
+        {"name": "staging", "type": "remote", "dialect": "postgres", "database": "app", "isActive": false, "isTest": false, "access": {"user": "admin", "agent": "viewer"}}
+    ]
+}
 ```
 
+Configs whose `access.agent` is `false` are omitted when the caller resolves to the `agent` channel — the same filtering the `list_configs` MCP command applies.
+
 
 #### `config use <name>`
 
@@ -246,6 +257,7 @@ noorm config use production --json
 **JSON output:**
 ```json
 {
+    "success": true,
     "activeConfig": "production"
 }
 ```
@@ -285,13 +297,14 @@ noorm config rm staging --yes --json
 **JSON output:**
 ```json
 {
+    "success": true,
     "name": "staging",
     "deleted": true
 }
 ```
 
 ::: danger Destructive
-Requires `--yes` (or `NOORM_YES=1`) — there is no TTY confirmation prompt, so the flag is mandatory even at an interactive terminal. An unknown config name fails with exit 1. Gated by the config's `config:rm` access (see [Access Roles](#access-roles) above); a config linked to a locked stage cannot be removed until the stage is unlocked.
+Requires `--yes` (or `NOORM_YES=1`) — there is no TTY confirmation prompt, so the flag is mandatory even at an interactive terminal. An unknown config name fails with exit 2. Gated by the config's `config:rm` access (see [Access Roles](#access-roles) above); a config linked to a locked stage cannot be removed until the stage is unlocked.
 :::
 
 
@@ -308,11 +321,13 @@ noorm config cp dev prod --json
 ```json
 {
     "success": true,
-    "source": "dev",
-    "destination": "staging"
+    "src": "dev",
+    "dest": "staging"
 }
 ```
 
+A destination name that already exists fails with exit 1; `config cp` has no `--force`.
+
 
 #### `config export <name>`
 
@@ -325,7 +340,11 @@ noorm config export dev --output ./dev-config.json
 
 | Flag | Description |
 |------|-------------|
-| `-o, --output` | Write to file instead of stdout |
+| `-o, --output` | Write to file instead of stdout (mode `0600`) |
+
+Plain `config export dev` writes the bare config object — the exact shape `config import` reads — so `noorm config export dev > dev.json` round-trips. `--json` wraps it in the envelope instead (`{"success": true, "name": "dev", "config": {…}}`), which is not importable as-is.
+
+The export carries the connection password in plaintext, so it is gated by `secret:read`: a `viewer` is denied.
 
 
 #### `config import <path>`
@@ -334,12 +353,13 @@ Import a configuration from a JSON file.
 
 ```bash
 noorm config import ./dev-config.json
-noorm config import ./staging-config.json --force
+noorm config import ./staging-config.json --force --yes
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--force` | Overwrite existing config with the same name |
+| `--force` / `-f` | Overwrite existing config with the same name |
+| `--yes` / `-y` | Confirm the overwrite. Required with `--force`, because replacing a config rewrites its `access` roles — a `config:write` confirm cell for every role that holds it |
 
 
 #### `config validate <name>`
@@ -356,12 +376,15 @@ noorm config validate production --json
 {
     "success": true,
     "config": "dev",
-    "dialect": "postgres",
-    "durationMs": 120
+    "valid": true,
+    "checks": [
+        {"label": "Connection", "status": "success", "detail": "Connection successful"},
+        {"label": "Name", "status": "success", "detail": "dev"}
+    ]
 }
 ```
 
-Exit code 0 if valid, 1 if connection fails.
+Exit code 0 if valid, 1 if any check fails, 2 if the config name is unknown.
 
 
 ### Identity
@@ -374,7 +397,7 @@ Create a new cryptographic identity. Generates an X25519 keypair and stores it a
 
 ```bash
 noorm identity init --name "Alice" --email "alice@example.com"
-noorm identity init --name "Alice" --email "alice@example.com" --force
+noorm identity init --name "Alice" --email "alice@example.com" --force --yes
 noorm identity init --name "Alice" --email "alice@example.com" --json
 ```
 
@@ -382,11 +405,17 @@ noorm identity init --name "Alice" --email "alice@example.com" --json
 |------|-------------|
 | `--name` | Display name (required) |
 | `--email` | Email address (required) |
-| `--force` | Overwrite existing identity |
+| `--force` | Replace an existing identity. Requires `--yes` |
+| `--yes` / `-y` | Confirm the replacement. The flag is read literally here, so an ambient `NOORM_YES` does not satisfy it |
+
+::: danger Destructive
+The state encryption key derives from the private key, so replacing an identity orphans every `state.enc` on the machine — configs, secrets, and database passwords become permanently undecryptable. Nothing re-encrypts existing state under the new key. The old keypair is backed up first, and its path lands in `backedUpTo` on the result; restoring `identity.key` from it is the only way back.
+:::
 
 **JSON output:**
 ```json
 {
+    "success": true,
     "name": "Alice",
     "email": "alice@example.com",
     "fingerprint": "...",
@@ -653,7 +682,11 @@ noorm run build --dry-run  # Preview without executing
 **JSON output:**
 ```json
 {
+    "success": true,
     "status": "success",
+    "files": [
+        {"filepath": "sql/01_tables/users.sql", "status": "success", "checksum": "…", "durationMs": 12}
+    ],
     "filesRun": 2,
     "filesSkipped": 1,
     "filesFailed": 0,
@@ -661,6 +694,8 @@ noorm run build --dry-run  # Preview without executing
 }
 ```
 
+**Exit codes:** `0` success, `1` complete failure, `3` partial failure (some files ran, some failed).
+
 
 #### `run file <path>`
 
@@ -675,8 +710,10 @@ noorm run file sql/init.sql --json
 **JSON output:**
 ```json
 {
+    "success": true,
     "filepath": "seed.sql",
     "status": "success",
+    "checksum": "…",
     "durationMs": 45
 }
 ```
@@ -692,6 +729,8 @@ noorm run dir seeds/
 noorm run dir migrations/ --json
 ```
 
+A directory that does not exist, or that holds no SQL files, exits `2` — a directory with nothing in it is a mistyped path, not a successful no-op.
+
 
 #### `run exec <path>`
 
@@ -729,6 +768,7 @@ noorm run inspect sql/core/Crons.sql.tmpl --json
 **JSON output:**
 ```json
 {
+    "success": true,
     "filepath": "sql/users/001_create.sql.tmpl",
     "context": {
         "dataFiles": [{"key": "roles", "type": "Array [3]"}],
@@ -757,12 +797,15 @@ noorm run preview sql/migrations/002.sql.tmpl --config staging
 **JSON output:**
 ```json
 {
+    "success": true,
     "filepath": "sql/schema.sql.tmpl",
     "sql": "CREATE TABLE ...",
     "durationMs": 12
 }
 ```
 
+A missing template exits `2`. In text mode the rendered SQL is the only thing on stdout, so `noorm run preview x.sql.tmpl > rendered.sql` stays pipeable; warnings go to stderr.
+
 
 ### Change Operations
 
@@ -772,7 +815,7 @@ Bare `noorm change` renders citty's help output and does not connect to the data
 
 | Command | Picker includes |
 |---------|-----------------|
-| `change run` | pending + reverted (not orphaned) |
+| `change run` | pending + reverted + stale (not orphaned) |
 | `change revert` | success |
 | `change rewind` | success |
 | `change edit` | every directory under `changes/` (filesystem) |
@@ -794,10 +837,14 @@ noorm change list -c staging
 
 **JSON output:**
 ```json
-[
-    {"name": "2024-01-15-init-schema", "status": "success"},
-    {"name": "2024-02-01-notifications", "status": "pending"}
-]
+{
+    "success": true,
+    "changes": [
+        {"name": "2024-01-15-init-schema", "status": "success"},
+        {"name": "2024-02-01-notifications", "status": "pending"}
+    ],
+    "pending": 1
+}
 ```
 
 
@@ -814,23 +861,28 @@ noorm change ff --force
 **JSON output:**
 ```json
 {
+    "success": true,
     "status": "success",
-    "applied": 2,
+    "executed": 2,
     "skipped": 0,
     "failed": 0,
+    "durationMs": 90,
     "changes": [
         {"name": "2024-02-01-notifications", "status": "success", "durationMs": 45}
     ]
 }
 ```
 
+`--dry-run` adds `"dryRun": true` to the payload. A missing `changes/` directory is a warning, not a failure: it lands in `warnings` rather than making the batch fail.
+
 
 #### `change next`
 
-Apply the next pending change only.
+Apply the next pending change. An optional positional count applies the next `n` instead of one.
 
 ```bash
 noorm change next
+noorm change next 3
 noorm change next --json
 ```
 
@@ -848,16 +900,19 @@ noorm change run 2024-02-01-notifications --json
 **JSON output:**
 ```json
 {
+    "success": true,
     "name": "2024-02-01-notifications",
     "direction": "change",
     "status": "success",
     "files": [
-        {"filepath": "change/001_create-table.sql", "checksum": "a1b2c3", "status": "executed", "durationMs": 23}
+        {"filepath": "change/001_create-table.sql", "checksum": "a1b2c3", "status": "success", "durationMs": 23}
     ],
     "durationMs": 45
 }
 ```
 
+`direction` is `change` or `revert`. Per-file `status` is one of `pending`, `success`, `failed`, `skipped`; the change-level `status` adds `reverted` and `stale`.
+
 
 #### `change revert [name]`
 
@@ -927,23 +982,31 @@ View execution history with timestamps, direction, and duration.
 ```bash
 noorm change history
 noorm change history --json
+noorm change history --count 50
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--count` | Show the last N records (default: 20) |
+
 **JSON output:**
 ```json
-[
-    {
-        "id": 1,
-        "name": "001_init",
-        "direction": "change",
-        "status": "success",
-        "executedAt": "2024-01-15T10:30:00Z",
-        "executedBy": "Alice <alice@example.com>",
-        "durationMs": 45,
-        "errorMessage": null,
-        "checksum": "abc123def456"
-    }
-]
+{
+    "success": true,
+    "history": [
+        {
+            "id": 1,
+            "name": "001_init",
+            "direction": "change",
+            "status": "success",
+            "executedAt": "2024-01-15T10:30:00Z",
+            "executedBy": "Alice <alice@example.com>",
+            "durationMs": 45,
+            "errorMessage": null,
+            "checksum": "abc123def456"
+        }
+    ]
+}
 ```
 
 
@@ -967,9 +1030,12 @@ Create the target database if it does not exist. Connects to the dialect's syste
 ```bash
 noorm db create
 noorm db create -c dev
+noorm db create --yes
 noorm db create --json
 ```
 
+Gated by the config's `db:create` access: `viewer` is denied, `operator` needs `--yes` (or `NOORM_YES=1`), `admin` runs unconfirmed. The gate fires before any probe touches the server, so a denied role never gets a SQLite file created as a side effect of the existence check.
+
 
 #### `db drop`
 
@@ -1013,20 +1079,29 @@ noorm db explore procedures             # List all procedures
 noorm db explore indexes                # List all indexes
 noorm db explore types                  # List custom types
 noorm db explore fks                    # List foreign keys
+noorm db explore triggers               # List triggers
 noorm db explore --json                 # JSON overview
 ```
 
 **JSON output (overview):**
 ```json
 {
+    "success": true,
     "tables": 12,
     "views": 3,
-    "indexes": 8,
+    "procedures": 0,
     "functions": 2,
-    "procedures": 0
+    "types": 4,
+    "indexes": 8,
+    "foreignKeys": 6,
+    "triggers": 1,
+    "locks": 0,
+    "connections": 3
 }
 ```
 
+`locks` and `connections` are runtime state, not schema, so they appear only in `--json` — the text overview lists the eight counters that have a drill-down subcommand.
+
 
 #### `db truncate`
 
@@ -1034,8 +1109,21 @@ Wipe all data from application tables. Schema and noorm tracking tables are pres
 
 ```bash
 noorm db truncate -y
+noorm db truncate --dry-run
+noorm db truncate --preserve seeds,lookups --yes
+noorm db truncate --only users,posts --yes
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--preserve` | Comma-separated tables to leave untouched |
+| `--only` | Comma-separated tables to truncate, to the exclusion of all others |
+| `--dry-run` | List the statements without executing them |
+
+::: warning Access Roles
+Gated by the config's `db:truncate` access: `viewer` is denied, `operator` and `admin` both confirm (`--yes`, or `NOORM_YES=1` in CI). There is no `--force` override — see [Access Roles](#access-roles) above.
+:::
+
 
 #### `db teardown`
 
@@ -1043,10 +1131,19 @@ Drop all database objects.
 
 ```bash
 noorm db teardown -y
+noorm db teardown --dry-run
+noorm db teardown --preserve-schemas app_private --yes
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--preserve-schemas` | Comma-separated schemas to leave untouched (teardown otherwise reaches every non-system schema) |
+| `--dry-run` | Report what would be dropped without dropping it |
+
+A teardown whose post-teardown script failed exits `1` even though the objects are already gone — a half-finished teardown must not report success.
+
 ::: warning Access Roles
-`db teardown` is gated by the config's `db:reset` access: `viewer` is denied, `operator` must confirm (`yes-<config>`, or `NOORM_YES=1` in CI), `admin` runs unconfirmed. There is no `--force` override — see [Access Roles](#access-roles) above.
+Gated by the config's `db:teardown` access: `viewer` and `operator` are denied outright, `admin` confirms (`--yes`, or `NOORM_YES=1` in CI). There is no `--force` override — see [Access Roles](#access-roles) above.
 :::
 
 
@@ -1067,16 +1164,18 @@ noorm db transfer --to backup --dry-run
 ```bash
 noorm db transfer --export ./backup/
 noorm db transfer --export ./backup/ --compress
-noorm db transfer --export ./backup/ --passphrase secret
+noorm db transfer --export ./backup/ --passphrase "correct-horse-battery"
 noorm db transfer --export ./backup/users.dt --tables users
 ```
 
 **Import from files:**
 ```bash
 noorm db transfer --import ./backup/users.dt
-noorm db transfer --import ./backup/users.dtzx --passphrase secret --on-conflict skip
+noorm db transfer --import ./backup/users.dtzx --passphrase "correct-horse-battery" --on-conflict skip
 ```
 
+`--passphrase` implies encryption, so the export lands as `.dtzx` whether or not you also pass `--compress`. On export it must be at least 12 characters; on import there is no floor, so archives encrypted with an older, shorter passphrase still open. Omit it on a TTY and noorm prompts with masked input; in a non-interactive session or under `--json`, omitting it exits `2`.
+
 **Transfer flags:**
 
 | Flag | Description |
@@ -1127,9 +1226,15 @@ Acquire an exclusive lock.
 
 ```bash
 noorm lock acquire
+noorm lock acquire --timeout 600000 --reason "nightly migration"
 noorm lock acquire --json
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--timeout` | Lock duration in milliseconds before it expires (default: 300000) |
+| `--reason` | Text shown to anyone this lock blocks |
+
 **CI/CD pattern with cleanup:**
 ```bash
 noorm lock acquire
@@ -1149,12 +1254,15 @@ noorm lock release
 
 #### `lock force`
 
-Force release any lock regardless of ownership.
+Force release any lock regardless of ownership. Gated by the config's `lock:force` access, which is a confirm cell for both `operator` and `admin`, so `--yes` (or `NOORM_YES=1`) is required.
 
 ```bash
-noorm lock force
+noorm lock force --yes
+noorm lock force -c prod --yes --json
 ```
 
+Exits `0` when a lock was actually broken and `2` when there was nothing to release, so a script can tell "evicted a holder" from "no-op" without parsing text. The `--json` payload reports `success` as whether a lock was broken, not whether the command ran.
+
 ::: warning
 Force releasing a lock can cause data corruption if the original holder is still running.
 :::
@@ -1180,15 +1288,21 @@ noorm vault init --json
 ```
 
 
-#### `vault set <key> <value>`
+#### `vault set <key> [value]`
 
 Store an encrypted secret in the vault.
 
 ```bash
 noorm vault set API_KEY "sk-live-abc123"
+echo "$API_KEY" | noorm vault set API_KEY --stdin
 noorm vault set API_KEY "sk-live-abc123" --json
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--stdin` | Read the value from stdin instead of argv, so it never reaches the process table, shell history, or a `set -x` trace. Omit the positional value when you pass it |
+| `--yes` / `-y` | Confirm the write on a config whose `vault:write` access is a confirm cell (an `operator` user role) |
+
 Upserts: creates if new, updates if the key exists.
 
 
@@ -1218,52 +1332,69 @@ noorm vault list --json
 
 #### `vault rm <key>`
 
-Remove a secret from the vault.
+Remove a secret from the vault. `--yes` (or `NOORM_YES=1`) is mandatory: the vault has no soft-delete and no history table, so this destroys the team's only copy.
 
 ```bash
-noorm vault rm OLD_API_KEY
-noorm vault rm OLD_API_KEY --json
+noorm vault rm OLD_API_KEY --yes
+noorm vault rm OLD_API_KEY --yes --json
 ```
 
+A key that was never in the vault exits `2`, which is distinct from a delete that failed (`1`).
+
 
-#### `vault cp`
+#### `vault cp <key> <source> <destination>`
 
-Copy secrets between config vaults.
+Copy one secret from one config's vault to another's. All three arguments are positional and required — there is no bulk mode.
 
 ```bash
 noorm vault cp API_KEY staging production
-noorm vault cp --all staging production
-noorm vault cp --all --force staging production
-noorm vault cp --all --dry-run staging production
+noorm vault cp API_KEY staging production --dry-run
+noorm vault cp DB_PASSWORD dev staging --force
+noorm vault cp API_KEY staging production --json
 ```
 
 | Flag | Description |
 |------|-------------|
-| `--all` | Copy all secrets from source |
-| `--force` | Overwrite existing secrets in destination |
+| `--force` / `-f` | Overwrite the key if it already exists in the destination |
 | `--dry-run` | Preview without executing |
 
-Without `--force`, existing secrets in the destination are skipped.
+Without `--force`, a key that already exists in the destination is skipped. An unknown source or destination config exits `2`.
 
 
 #### `vault propagate`
 
 Grant vault access to team members who don't have it yet. Encrypts the vault key with each pending user's public key.
 
+Propagation seals the vault key to a public key and cannot be revoked, so a bare `noorm vault propagate` only *lists* the identities awaiting access and exits `1`. Re-run with `--yes` to grant, or `--to <hash>` to grant to specific identities.
+
 ```bash
-noorm vault propagate
+noorm vault propagate                        # review the pending list
+noorm vault propagate --yes                  # grant to everyone pending
+noorm vault propagate --to 4a5c14af... --yes # grant to one identity
 noorm vault propagate --json
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--to` | Comma-separated identity hashes to grant to (default: every pending identity) |
+| `--yes` / `-y` | Perform the grant. Without it the command reports and stops |
+
 **JSON output:**
 ```json
 {
     "success": true,
-    "propagatedTo": ["alice@example.com"],
-    "alreadyHadAccess": 3
+    "granted": true,
+    "propagatedTo": ["4a5c14af…"],
+    "alreadyHadAccess": 3,
+    "failed": [],
+    "pending": [
+        {"identityHash": "4a5c14af…", "name": "Alice", "email": "alice@example.com"}
+    ]
 }
 ```
 
+`propagatedTo` holds identity hashes; `pending` is what maps them back to a name and email. A grant that lands for some identities and not others exits `3` with `success: false` — the vault is in a mixed state, and the teammate whose update did not land believes they have access.
+
 
 ### SQL Operations
 
@@ -1273,8 +1404,8 @@ Execute a raw SQL query.
 
 ```bash
 noorm sql "SELECT * FROM users LIMIT 10"
-noorm sql -f query.sql
-noorm -c prod sql "SELECT count(*) FROM orders"
+noorm sql query -f query.sql
+noorm sql query -c prod "SELECT count(*) FROM orders"
 noorm sql "SELECT id, name FROM users" --json
 ```
 
@@ -1283,6 +1414,8 @@ noorm sql "SELECT id, name FROM users" --json
 | `-f, --file` | Read SQL from a file |
 | `-c, --config` | Use specific configuration |
 
+The bare `noorm sql "<SQL>"` form works by rewriting argv to `noorm sql query "<SQL>"`, and it only fires when the first non-flag token after `sql` looks like SQL. A flag that takes a value puts something else there, so `noorm sql -f query.sql` and `noorm sql -c prod "SELECT 1"` print help instead — spell out `query` with either. See [`noorm sql`](./cli/sql.md).
+
 **JSON output:**
 ```json
 {
@@ -1292,11 +1425,12 @@ noorm sql "SELECT id, name FROM users" --json
         {"id": 1, "name": "Alice"},
         {"id": 2, "name": "Bob"}
     ],
-    "rowsAffected": null,
     "durationMs": 12.5
 }
 ```
 
+`rowsAffected` replaces the row payload for INSERT/UPDATE/DELETE and is absent (not `null`) on a SELECT.
+
 
 #### `sql repl`
 
@@ -1312,13 +1446,13 @@ noorm sql repl --config dev
 
 #### `sql history`
 
-Show SQL execution history.
+Show SQL execution history. Only the interactive SQL terminal records history — `sql query` deliberately writes none, so persisting query text and returned rows on a build agent never happens.
 
 ```bash
 noorm sql history
 noorm sql history -n 20
 noorm sql history --json
-noorm -c prod sql history
+noorm sql history -c prod
 ```
 
 | Flag | Description |
@@ -1333,13 +1467,15 @@ Clear SQL execution history.
 ```bash
 noorm sql clear --yes
 noorm sql clear --older-than 3 --yes
-noorm -c prod sql clear --yes
+noorm sql clear -c prod --yes
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--older-than` | Only clear entries older than N months |
-| `--yes` | Confirm without prompt (required) |
+| `--yes` / `-y` | Confirm. Without it the command reports what it would clear and exits 0 without clearing |
+
+`--json` also counts as a confirmation, since it is only used non-interactively.
 
 
 ### MCP (AI Agent Integration)
@@ -1380,20 +1516,29 @@ noorm info --json
 **JSON output:**
 ```json
 {
+    "success": true,
     "cli_version": "1.0.0-alpha.34",
-    "schema_version": 1,
+    "schema_version": 2,
+    "state_version": 3,
+    "settings_version": 1,
+    "installed_at": "2024-01-15T10:30:00.000Z",
+    "upgraded_at": null,
     "active_config": "dev",
     "config_count": 2,
     "connection": {
         "host": "localhost",
         "port": 5432,
         "database": "mydb",
-        "dialect": "postgresql"
+        "dialect": "postgres"
     },
     "identity": {
         "name": "Your Name",
-        "email": "you@example.com"
+        "email": "you@example.com",
+        "machine": "laptop",
+        "registered_at": "2024-01-15T10:30:00.000Z",
+        "last_seen_at": "2024-02-01T09:00:00.000Z"
     },
+    "agent": null,
     "objects": {
         "tables": 5,
         "views": 12,
@@ -1404,6 +1549,8 @@ noorm info --json
 }
 ```
 
+`connection` is `null` and `connection_error` carries the message when the active config can't be reached. `agent` names the AI harness noorm detected, if any, along with the env markers that gave it away — worth checking first when a permission denial has no visible cause, since harness detection is what flips the policy channel from `user` to `agent`.
+
 
 #### `version`
 
@@ -1424,6 +1571,10 @@ noorm update
 noorm update --json
 ```
 
+| Flag | Description |
+|------|-------------|
+| `--insecure` | Downgrade an unreachable `checksums.txt` from a failure to a warning. Also settable as `NOORM_INSECURE=1`. It never bypasses a confirmed checksum mismatch, which always fails |
+
 
 #### `ui`
 
@@ -1709,7 +1860,7 @@ echo "Database has $tables tables"
 # Verify vault access
 pending=$(noorm vault list --json | jq '.status.usersWithoutAccess')
 if [ "$pending" -gt 0 ]; then
-    noorm vault propagate
+    noorm vault propagate --yes
 fi
 ```
 
diff --git a/docs/index.md b/docs/index.md
index 81a2f03b..cdbf5ede 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -69,6 +69,8 @@ Everything else follows from that split:
 - **The SDK** wraps it all in a type-safe client — Kysely queries, stored procedures, and TVFs
 - **Headless mode** makes every command scriptable, with `--json` on anything worth parsing
 
+noorm is the fifth attempt at this problem, and every feature in it exists because working without an ORM was worse without it. [Why noorm](/why-noorm) is the longer version of that story.
+
 
 ## Quick start
 
@@ -131,6 +133,20 @@ noorm vault set API_KEY ... # Push a team secret to the encrypted vault
 ```
 
 
+## Plan it before you build it
+
+Most schemas get designed while they are being built, one migration at a time, and nobody outside the code can see the shape until it is already in production.
+
+[ignatius](/modeling/) is the planning half. Describe your entities and processes in markdown and it renders an IDEF1X entity diagram, a searchable data dictionary, and SSADM data flow diagrams that show how data moves between people, the database, caches, files, and paper. Export it to a single HTML file, get agreement from the people who care, then hand the same markdown to your agent as the specification for the SQL.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/noormdev/ignatius/main/install.sh | sh
+ignatius serve ./models -o
+```
+
+ignatius decides what the data is. noorm builds it. Both keep the source of truth in files you own. See [Information modeling](/modeling/).
+
+
 ## Next steps
 
 <div class="next-steps">
@@ -144,4 +160,7 @@ Complete the tutorial and see the core value.
 [**Building Your SDK**](/getting-started/building-your-sdk)
 Create a type-safe database package for your apps.
 
+[**Information Modeling**](/modeling/)
+Design the data model before you write the schema.
+
 </div>
diff --git a/docs/modeling/best-practices.md b/docs/modeling/best-practices.md
new file mode 100644
index 00000000..bdde8fca
--- /dev/null
+++ b/docs/modeling/best-practices.md
@@ -0,0 +1,149 @@
+---
+title: Modeling best practices
+description: How to produce an ignatius model that survives a stakeholder review and is worth handing to an agent as a specification.
+---
+
+# Modeling best practices
+
+
+A model earns its keep when someone who does not write SQL can read it, disagree with it, and be right. These are the habits that get you there.
+
+
+## Model the decision, not the storage
+
+
+The question a model answers is what the data is and how it is identified. Column types are logical for that reason: `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `binary`. Whether a column becomes `VARCHAR(255)` or `TEXT`, which index it gets, and how it partitions are build-time decisions that belong in the SQL files noorm runs.
+
+Keeping those out of the model is what makes it reviewable by the people whose sign-off you need.
+
+
+## Write the body
+
+
+The frontmatter is the structure. The body is the reason the entity exists, and it is the part of the model that a schema dump can never give you.
+
+Say what the thing is in business terms, what it is not, and what rule made you draw the boundary where you did. The reference model's `Party` entity explains why customers, vendors, and employees are one entity rather than three: a company that is both a customer and a vendor should not have two identities, and a person who becomes a customer after being an employee keeps one record. That paragraph is what a stakeholder argues with. The column list is not.
+
+Link related entities in prose with `[[Entity]]`. A wiki link that points at a nonexistent entity renders muted and raises `body.unknown_link`, so the prose stays honest as the model changes.
+
+
+## Always include examples
+
+
+Add two or three realistic rows to every entity and input and output tables to every process. The modeling skill does this by default, and it is worth keeping when you author by hand.
+
+Structural validation cannot catch a wrong rule, only a broken reference. Concrete instances can. Write the rows for a case you believe is legal, and if one of them looks wrong when you read it back, the rule is wrong. This is the cheapest modeling test that exists, and it is the one that finds the errors that survive to production.
+
+
+## Let derivation do its job
+
+
+Do not declare `classification`, `identifying`, or cardinality. Describe the primary key, the columns, and the `on:` mapping, and let ignatius work out the rest.
+
+Two reasons. The derived answer stays correct when the key shape changes, and a hand-written label does not. And nothing reads those labels anyway: `identifying` and cardinality have no frontmatter field at all, and the only classification the parser accepts is `reference: true` for a lookup or code table. A `classification:` you set by hand is ignored without a finding, so it drifts out of agreement with the diagram in silence.
+
+
+## Choose a key convention on purpose
+
+
+Decide whether an entity inherits its parent's key or carries a surrogate `id`, and be able to say why.
+
+Inherited keys carry lineage in the identity, so a child cannot be attached to the wrong parent and the owning party is available without a join. They also make the lineage spotlight useful, since the feature works on shared-key families and has nothing to show on an all-surrogate schema. Surrogate keys are simpler to write and fit reference tables that nothing depends on for identity.
+
+Mixing conventions per entity is supported and often correct: a transactional spine that inherits keys alongside lookup tables that do not. Record the reason in the entity body so the next reader sees a decision instead of an inconsistency.
+
+When a team disagrees about this, serve the three reference variants that ship with ignatius (`key-inherited`, `orm-hybrid`, `orm-pure`) and compare them directly. They model the same business with the same entities, so the only variable is the keys.
+
+
+## Name processes as verbs
+
+
+A process transforms data. `Collect-Payment`, `Issue-Invoice`, and `Validate-Customer` read as work. A noun like `Payment-Handler` describes a component, and components belong in an architecture diagram rather than a DFD.
+
+The file name minus `.md` becomes the process id used in `proc:` tokens, wiki links, and the sub-diagram folder name, so pick it once and pick it well.
+
+
+## Enumerate what a flow carries
+
+
+On a `db:` endpoint the `data:` field is a column list, validated against the entity's keys and columns. On any other endpoint it is free text, and free text is where flows go vague.
+
+Write "gateway transaction reference, HTTP status, raw response" rather than "log data". The label is the contract for what crosses that arrow, and a reviewer can only catch a missing field if the field would have been named. Anything long is truncated on the canvas with an ellipsis and shown in full on hover, so a thorough label costs you nothing visually.
+
+
+## Model the stores that are not tables
+
+
+The caches, log files, queues, exported spreadsheets, signed forms, and PDFs are where the surprises live. They hold data nobody versioned, nobody backed up, and nobody remembered when the retention policy was written.
+
+Give each one a `stores/<name>.md` with its kind and a body explaining why it exists, what is written to it, and what happens to it over time. "Append-only log of raw gateway responses, never read back during normal processing, retained for 7 years" is a compliance fact that exists in no schema and in no codebase.
+
+
+## Decompose only where it earns it
+
+
+A sub-diagram is a folder named exactly after its parent process, and it must stay balanced with that parent: the data crossing its boundary has to match the parent's declared inputs and outputs, column for column on `db:` flows. `flow.unbalanced_decomposition` enforces that at every level.
+
+That check is a feature, and it is also a cost. Decompose a process when the detail changes a decision, not to show completeness. Two levels that stay balanced beat four that drift.
+
+
+## Keep validate clean
+
+
+`ignatius validate` exits `1` on errors and `0` otherwise, and warnings alone do not fail it. Run it while authoring and wire it into CI next to your other checks.
+
+Treat warnings as a queue rather than noise. `entity.unknown_group`, `cluster.no_discriminator`, and `flow.unknown_attribute` each name a real gap: a group file you never wrote, an exclusive cluster with no way to tell its subtypes apart, a flow promising a column the entity does not have. The model that fails a review is usually the one that accumulated twenty warnings nobody read.
+
+The `models/broken-demo` folder in the ignatius repo is deliberately broken to exercise every rule, which makes it a fast way to learn what each finding looks like before you meet it on your own model.
+
+
+## Review before you build
+
+
+Export the model and put it in front of someone.
+
+```bash
+ignatius export ./models -o model.html
+```
+
+One self-contained HTML file with the graph, the dictionary, and the flows, working offline with nothing installed. Attach it to the ticket, mail it to the stakeholder, or commit it beside the model.
+
+Put your own name on it first. The default logo, title, and copyright line are placeholders, and a document going to a client or an approver should carry your organization rather than the tool's. See [Branding your model](/modeling/branding).
+
+This is the step the whole tool exists for. A wrong entity boundary costs a conversation now and a migration later. Get the disagreement out of people before the schema is real, then hand the agreed model to your agent as the specification for the SQL.
+
+
+## Keep the model next to the code
+
+
+Commit the model folder in the repository whose schema it describes. It diffs cleanly, so a schema change and its model change land in one reviewable commit, and the prose explaining why gets reviewed alongside the DDL.
+
+A model that lives in a wiki or a drawing tool drifts within a quarter. One that lives in the repo and gates CI does not.
+
+
+## A model that follows all of this
+
+
+Reading a finished model beats reading rules about one. [`models/llm-memory-db-mssql`](https://github.com/noormdev/ignatius/tree/main/models/llm-memory-db-mssql) in the ignatius repo is the memory database an AI coding agent writes to, and it is the model in the [demo recording](/modeling/#information-modeling).
+
+```bash
+git clone https://github.com/noormdev/ignatius.git
+ignatius serve ignatius/models/llm-memory-db-mssql -o
+```
+
+It runs 38 entities across 8 groups, 27 processes in 6 diagrams, and one external actor, and `ignatius validate` reports no findings. Things worth looking at while it is open:
+
+- **Every entity and every process carries examples.** All 38 and all 27, with no exceptions, which is what the practice above asks for and what most models skip first.
+- **The key conventions are mixed on purpose.** `Agent` and `Artifact` are surrogate roots, while `Milestone` → `Task` (`milestone_id, task_no`) → `Task_Artifact` (`milestone_id, task_no, artifact_id`) inherits the whole way down. The transactional spine inherits; the things with independent identity do not.
+- **Classification is visible, not declared.** Reference tables, associatives like `Memory_Tag`, and the `StateTransition` subtype cluster all get their shape from their keys.
+- **The bodies carry business rules.** `Agent` explains why rows default `agent_id` to a sentinel: memories written before an agent existed, or after one is deleted, stay intact instead of being orphaned. No schema records that.
+
+Two practices it does not exercise, because the domain has no occasion for them: it has no non-`db` stores and no sub-diagrams. For those, read [`models/key-inherited`](https://github.com/noormdev/ignatius/tree/main/models/key-inherited), which validates clean at 24 entities and has both a `file:` store with a retention policy in its body and a decomposed process with a balanced child diagram.
+
+
+## Related
+
+
+- [Entities and key inheritance](/modeling/entities)
+- [Data flows](/modeling/data-flows)
+- [The modeling skill](/modeling/modeling-skill)
diff --git a/docs/modeling/branding.md b/docs/modeling/branding.md
new file mode 100644
index 00000000..9400d61b
--- /dev/null
+++ b/docs/modeling/branding.md
@@ -0,0 +1,110 @@
+---
+title: Branding your model
+description: Put your own logo, title, and copyright on an ignatius model. The default chrome is a placeholder, not a claim on your work.
+---
+
+# Branding your model
+
+
+An ignatius model is yours. The entities, the prose, the flows, and the diagrams generated from them are your work product, and nothing about using the tool changes that.
+
+Out of the box the app wears noorm's chrome: a noorm logo, the title "Noorm Ignatius", the subtitle "Visualize your data model", and a footer reading "© 2026 Noorm Ignatius" above a "powered by Noorm" line, with the year taken from the current date. That is placeholder branding on a viewer you are expected to replace, not a claim on the model it displays. The copyright line exists so you have somewhere to put **your** organization, which is the point of it being configurable at all.
+
+Replace all of it in `ignatius.yml`.
+
+
+## The branding block
+
+
+Every field is optional and falls back to the default.
+
+```yaml
+name: My Schema
+branding:
+    logo:
+        dark: ./assets/logo-dark.svg
+        light: ./assets/logo-light.svg
+    title: Acme Corp Data Model
+    subtitle: Internal, revision 4
+    copyright:
+        holder: Acme Corp
+        year: 2026
+    poweredBy: false
+```
+
+| Field | Default | Notes |
+|---|---|---|
+| `logo` | embedded noorm logo | One path applies to both modes, or use `{ dark, light }` for per-mode logos |
+| `title` | `Noorm Ignatius` | Max 50 characters |
+| `subtitle` | `Visualize your data model` | Max 50 characters |
+| `copyright` | `{ holder: 'Noorm Ignatius', year: <current year> }` | Set `holder` to your organization |
+| `poweredBy` | `true` | Set `false` to drop the footer attribution |
+
+Setting `copyright.holder` and `poweredBy: false` removes every mention of noorm from the rendered model. Nothing asks you to keep the attribution, and no feature is gated behind it.
+
+Logo paths resolve relative to the model root and are inlined as data URIs when you `export`, so a branded model stays a single self-contained HTML file with no external requests.
+
+
+## Why this matters at export time
+
+
+`ignatius export` produces one HTML file you hand to somebody: a stakeholder approving the design, a client receiving a deliverable, an auditor reading a system description. That file is the artifact your organization's name belongs on.
+
+```bash
+ignatius export ./models -o acme-data-model.html
+```
+
+Brand the model before that hand-off rather than after. It costs six lines of YAML and it is the difference between a document that reads as yours and one that reads as a tool's output.
+
+
+## Colors and spacing
+
+
+A `theme` block sets separate `dark` and `light` palettes plus layout spacing. It is deep-merged over the defaults, so set only what you want to change.
+
+```yaml
+theme:
+    dark:
+        background: "#0e1116"
+        surface: "#161b22"
+        text: "#e6edf3"
+    light:
+        background: "#ffffff"
+        surface: "#f6f8fa"
+        text: "#1f2328"
+    spacing:
+        nodeSep: 60
+```
+
+The viewer's light/dark toggle persists across reloads, and `export` takes `--theme light` or `--theme dark` to pick the starting palette.
+
+
+### Data flow store colors
+
+
+In a [data flow diagram](/modeling/data-flows) each store is colored by its kind. The defaults give every kind a distinct, mode-appropriate color: `cache` amber, `queue` violet, `file` lime, `doc` sky, `manual` rose, `other` slate, while `db` keeps the entity-store fill and `external` keeps the conventional green.
+
+Override any of them under `theme.flowKinds`. Each kind takes `dark` and `light` entries of `{ bg, fg, border }`, deep-merged like the rest of the theme.
+
+```yaml
+theme:
+    flowKinds:
+        cache:
+            dark:
+                bg: "#3a2a00"
+            light:
+                bg: "#fff3c4"
+        file:
+            dark:
+                bg: "#16270a"
+```
+
+Worth restraint here. The kind colors are a legend readers learn once, and a palette tuned for your brand rather than for distinguishability makes a busy diagram harder to read. Change them to fit your house style, not to make every store the same shade of corporate blue.
+
+
+## Related
+
+
+- [Entities and key inheritance](/modeling/entities#the-folder-format) for the rest of `ignatius.yml`
+- [Best practices](/modeling/best-practices#review-before-you-build) for the review hand-off this feeds
+- The [themes and branding guide](https://github.com/noormdev/ignatius/blob/main/docs/guides/themes-and-branding.md) in the ignatius repo
diff --git a/docs/modeling/data-flows.md b/docs/modeling/data-flows.md
new file mode 100644
index 00000000..291d4008
--- /dev/null
+++ b/docs/modeling/data-flows.md
@@ -0,0 +1,181 @@
+---
+title: Data flows
+description: SSADM data flow diagrams in ignatius. Show how processes move data between people, the database, caches, files, and paper.
+---
+
+# Data flows
+
+
+An entity diagram tells you what the data is. It does not tell you who touches it, or where it rests when it is not in a table.
+
+ignatius answers that with data flow diagrams in the SSADM style, using Gane-Sarson notation: numbered process hubs, green external boxes for actors outside the system, and open-ended `D#` boxes for stores. Flows live in the same folder as the entities, in the same markdown format, and a `db:` store in a diagram is the same entity you modeled in the graph. Click it and the full entity dialog opens, with columns, relationships, and examples.
+
+
+## Why the diagram includes more than tables
+
+
+The useful part of a DFD is that a data store is not required to be a database table.
+
+A cache holds derived state. A log file holds gateway responses nobody reads until a dispute. A queue holds work in flight. A signed paper form sits in a drawer, and a PDF sits in someone's mail. All of those are places your business keeps data, and all of them are places it can go missing, go stale, or leak. Model them and the diagram shows where information lives, including the parts that never reached the database.
+
+The same applies to people. An external entity is a source or a sink that sits outside the system boundary: a customer, a supplier, a regulator, a support agent. Drawing them makes the handoffs explicit, which is where most process defects are.
+
+Two distinctions are worth holding onto:
+
+- **Stores are inside the system, externals are outside it.** Both can be the source or the sink of a flow, but only a store represents state the system owns.
+- **Every entity is a store, not every store is an entity.** A `db:` store resolves to a real entity in the graph. A cache, file, queue, document, or manual record is a store and nothing more.
+
+
+## Folder layout
+
+
+Flows live in a `flows/` folder at the model root. Each diagram is a folder, and each process is a file inside it.
+
+```
+models/
+    ignatius.yml
+    data/
+        identity/ ...           # entities live under data/
+    externals/
+        Customer.md             # shared external, usable by every diagram
+    stores/
+        gateway-log.md          # optional description of a non-entity store
+    flows/
+        order-to-cash/
+            Create-Sales-Order.md   # process 1
+            Create-Sales-Order/     # same-named folder is the sub-diagram
+                Validate-Customer.md
+                Record-Order.md
+            Issue-Invoice.md        # process 2
+            Collect-Payment.md      # process 3
+        refund/
+            Process-Return.md
+```
+
+Files under `flows/` are never scanned as entities. The file name minus `.md` is the process id used everywhere: in `proc:` tokens, in wiki links, and as the sub-diagram folder name. Name it as an imperative phrase with hyphens for spaces, so `Collect Payment` becomes `Collect-Payment.md`.
+
+
+## A process file
+
+
+Frontmatter declares the data contract. The body explains the business. The arrows on the diagram are generated from `inputs:` and `outputs:`.
+
+```markdown
+---
+process: Collect Payment
+number: 3
+inputs:
+    - from: ext:Customer
+      data: payment details
+    - from: db:PaymentMethod
+      data: [party_id, payment_method_id, type, label]
+outputs:
+    - to: db:Payment
+      data: [party_id, payment_method_id, payment_id, amount]
+    - to: file:gateway-log
+      data: gateway transaction reference, HTTP status, raw response
+    - to: ext:Customer
+      data: receipt
+examples:
+    in:
+        - from: ext:Customer
+          label: payment details
+          rows:
+              - { card: "****4242", amount: 49.99, currency: GBP }
+    out:
+        - to: db:Payment
+          label: settled payment record
+          rows:
+              - { party_id: 1001, payment_method_id: 42, payment_id: 9001, amount: 49.99 }
+---
+
+Settles an invoice by recording a [[Payment]] and allocating it against the
+invoice line it pays. A receipt is returned to the [[Customer]].
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `process` | yes | The human label shown on the node |
+| `number` | no | Local rank among sibling processes, falling back to file order. Full SSADM numbers like `1.2.1` are composed from the folder nesting |
+| `inputs` / `outputs` | yes | The flows. Each names an endpoint and the `data:` it carries |
+| `examples` | no | Sample in and out rows, rendered as tables in the process dialog, one entry per flow |
+
+The `data:` field is both the arrow's label and its contract. On a `db:` endpoint it is always column names, a string for one or a list for several, and every name is checked against the entity's `pk` and `columns` under the `flow.unknown_attribute` rule. On any other endpoint it is an opaque label, so make it enumerate what the flow carries rather than summarize it in one word.
+
+Bodies support the same `[[Entity]]` wiki links as entity files, and can also link to processes, externals, and stores by name. Links open the target's dialog in place.
+
+
+## Endpoints
+
+
+Every flow connects a process to something. The token's prefix says what.
+
+| Token | Endpoint |
+|---|---|
+| `db:<Entity>` | A store backed by a modeled entity. Must match an entity id exactly |
+| `ext:<Name>` | An external entity, an actor outside the system boundary |
+| `proc:<Name>` | Another process, used for sub-diagram boundary flows |
+| `cache:` `queue:` `file:` `doc:` `manual:` `other:` | A non-entity store of that kind |
+
+The prefix set is closed. A store that fits none of the named kinds is authored as `other:<name>`; there is no way to invent a prefix. A bare, unprefixed name resolves only when it is unambiguous across all namespaces, and otherwise raises `flow.ambiguous_endpoint` asking you to qualify it.
+
+
+### Externals
+
+
+Describe an external once in `externals/<Name>.md` at the model root, with an `external:` label in frontmatter and a body covering its role, what it does, and what it expects back. Every diagram at any nesting depth can then reference `ext:<Name>`. There is no per-diagram override.
+
+
+### Stores
+
+
+A `db:` store needs no file. It is the entity, documented in the entity's own markdown. A non-`db` store exists by being referenced, and an optional `stores/<name>.md` adds a kind, a display title, and the reason it exists.
+
+```markdown
+---
+kind: file
+title: Payment Gateway Log
+---
+
+Append-only log of raw gateway responses. Used for reconciliation and dispute
+resolution; never read back during normal processing. Retained for 7 years.
+```
+
+A store file's `kind:` is one of `cache`, `queue`, `file`, `doc`, `manual`, or `other`. An absent or unrecognized value falls back to `other`. `db` is not in that list, because a `db:` store is the entity and needs no file. Kind drives the node's color in the diagram, theme-aware and overridable under `theme.flowKinds` in `ignatius.yml`.
+
+Writing that body is where the value is. "Retained for 7 years" and "never read back during normal processing" are the facts that decide whether the store is a compliance asset or a liability, and they exist nowhere in a schema.
+
+
+## Sub-diagrams
+
+
+A process decomposes by placing a folder with the process's exact file name next to its file. The folder holds the child diagram, with its own process files numbered locally, and full dotted numbers composed from the nesting. Decomposition recurses as deep as it needs to. There is no depth cap, and the ancestor chain is preserved at every level, so a process four layers down reads as something like `1.4.2.1`.
+
+The child diagram must be balanced with its parent: the data crossing the sub-diagram's boundary has to match the parent process's declared inputs and outputs, column for column on `db:` flows. The `flow.unbalanced_decomposition` rule checks that at every level, which is the thing hand-drawn DFDs always get wrong once the diagram is more than one page.
+
+In the viewer, a process with a sub-diagram renders with a stacked-shadow affordance. Clicking drills down, and a breadcrumb leads back up.
+
+
+## Viewing and validating
+
+
+`ignatius serve` shows flows in the Flows view at `#view=flow`. The active diagram is deep-linkable through the `dfd=` hash parameter and survives a refresh. `ignatius export` writes the Flows view into the same single HTML file as the other two views.
+
+Every node carries an ⓘ badge. A `db:` store opens the rich entity dialog; a process, external, or non-`db` store opens its markdown. The process dictionary, meaning every process, external, and store with its body and its input and output tables, is fused into the Dictionary view and searchable alongside the entities.
+
+Hovering an edge that carries data reveals a tooltip listing everything crossing it, under a `source → target` header. That includes the full contents of `db:` column lists which are abbreviated on the canvas when they run long. Labels over 22 characters show a truncated preview with an ellipsis, so you can always see at a glance which edges are hiding detail, and the tooltip stays legible at any zoom level.
+
+`ignatius validate` runs twelve `flow.*` rules whenever a `flows/` directory exists, covering unknown references, column contracts, connection shape, numbering, store-token conflicts, and decomposition balance. One rule is configurable: direct process-to-process flows warn by default and can be silenced with `flow_rules: { process_to_process: false }` in `ignatius.yml`.
+
+
+## Authoring with the skill
+
+
+The [`noorm-modeling` skill](/modeling/modeling-skill) has two doors into flows. `/noorm-modeling flow` walks you through a diagram step by step when you can already name your processes. `/noorm-modeling discover` interviews you about how the business runs and generates both the entities and the flows. Both verify their output with `ignatius validate`.
+
+
+## Related
+
+
+- [Entities and key inheritance](/modeling/entities) covers the entities these diagrams reference.
+- The [flows guide](https://github.com/noormdev/ignatius/blob/main/docs/guides/flows.md) and the [validation catalog](https://github.com/noormdev/ignatius/blob/main/docs/guides/validation.md) carry the exhaustive reference.
diff --git a/docs/modeling/entities.md b/docs/modeling/entities.md
new file mode 100644
index 00000000..e3427920
--- /dev/null
+++ b/docs/modeling/entities.md
@@ -0,0 +1,357 @@
+---
+title: Entities and key inheritance
+description: The ignatius entity format, what the tool derives from your key shape, and why IDEF1X key inheritance is the premise the whole tool is built on.
+---
+
+# Entities and key inheritance
+
+
+IDEF1X is the premise ignatius is built on. In IDEF1X an entity is defined by how it is identified, and identity flows down through relationships: a child that depends on a parent carries the parent's key inside its own. That single idea decides the cardinality of an edge, whether the edge is identifying, and how the entity gets classified. ignatius implements that premise directly. You describe the key shape, and the notation follows.
+
+You can still model an ORM-style schema where every table has one surrogate `id`. ignatius draws that correctly too. It is not what the tool optimizes for.
+
+::: tip Modeling IDEF1X with an agent
+IDEF1X is a methodology, not a file format. The calls it asks you to make (what counts as an entity, where identity comes from, which relationships are identifying) are the ones no tool can make for you.
+
+If you want an agent reasoning in those terms alongside you, there is a separate [`idef1x` skill](https://www.skills.sh/damusix/skills/idef1x) that installs with the same `skills` CLI as the modeling skill:
+
+```bash
+npx skills add https://github.com/damusix/skills --skill idef1x
+```
+
+It advises on method. The [`noorm-modeling` skill](/modeling/modeling-skill) writes the files. Neither is required to use ignatius, and the rest of this page assumes neither.
+:::
+
+
+## The folder format
+
+
+A folder is a model root when it contains an `ignatius.yml` file. Five top-level folders are recognized, and everything else at the root is left alone.
+
+```
+models/
+    ignatius.yml
+    data/
+        identity/
+            Party.md
+            Person.md
+            Business.md
+        transactional/
+            SalesInvoice.md
+            SI_Line.md
+    groups/
+        identity.md
+        transactional.md
+    externals/          # optional, shared DFD externals
+    stores/             # optional, shared non-db DFD stores
+    flows/              # optional, data flow diagrams
+    notes/              # free-form, never scanned
+```
+
+Entities live under `data/`. The subdirectory is organizational convenience only: an entity's group comes from its `group:` frontmatter field, not from the folder it sits in. `groups/` is optional, and a model with no groups parses without error.
+
+`ignatius.yml` marks the root and carries display config. The minimum is one line.
+
+```yaml
+name: My Schema
+```
+
+Add `version`, `description`, and `updated` for model metadata, a `theme` block to override colors and spacing, and a `branding` block for a logo, title, or copyright line. The model is yours, and the default chrome is a placeholder you are meant to replace. See [Branding your model](/modeling/branding).
+
+
+## An entity file
+
+
+Frontmatter carries the structure. The body is free-form documentation. The attribute table you see in the viewer is generated from the frontmatter, so do not write one in the body.
+
+```markdown
+---
+entity: SalesInvoice
+group: transactional
+pk:
+    - party_id
+    - sales_invoice_id
+columns:
+    party_id:
+        type: integer
+        desc: "Billed party, foreign key to Party."
+    sales_invoice_id:
+        type: integer
+        desc: "Identifier of the invoice within the party."
+    issued_at:
+        type: datetime
+        desc: "Timestamp the invoice was issued."
+        default: now
+    total:
+        type: decimal
+        desc: "Invoice total; reconciles to the sum of its line items."
+examples:
+    - party_id: 2
+      sales_invoice_id: 5001
+      issued_at: "2024-03-05T14:25:00Z"
+      total: 138.00
+relationships:
+    - target: Party
+      on:
+          party_id: party_id
+      predicate: { fwd: owes on, rev: is owed by }
+---
+
+# SalesInvoice
+
+A **SalesInvoice** is a bill issued to a [[Party]] for amounts owed. It is the
+demand for payment, the document a `Payment` is ultimately applied against,
+line by line.
+```
+
+Note what is absent: no `classification`, no per-edge `identifying`, no `cardinality`. ignatius derives all three.
+
+
+### Columns
+
+
+Each column takes a logical `type` and three optional fields.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `type` | required | One of `text`, `integer`, `decimal`, `boolean`, `date`, `datetime`, `binary` |
+| `nullable` | `false` | Whether the column accepts null |
+| `default` | none | A default value note |
+| `desc` | none | A short note on what the column is for |
+
+The types are logical, not physical. ignatius models information, so it does not care whether your `text` becomes `VARCHAR(255)` or `TEXT`. That decision belongs in the SQL files noorm runs.
+
+
+### Relationships
+
+
+A relationship names a `target` entity and maps foreign-key columns with `on: { child_column: parent_column }`. The `predicate` labels the edge in the graph and the dictionary.
+
+```yaml
+relationships:
+    - target: Party
+      on:
+          party_id: party_id
+      predicate: is a
+```
+
+A predicate can carry both reading directions with `{ fwd, rev }`, so the edge reads correctly whichever way you traverse it.
+
+
+#### Lazy predicates and real ones
+
+
+In IDEF1X, entities are nouns and relationships are verbs. The predicate is where that verb goes, and it is the part of the model a tool cannot derive for you. Everything else on the edge comes from the keys.
+
+`has many`, `belongs to`, and `has one` are the reflex answers, and they are all restatements of something already on the diagram. "Party has many SalesOrders" tells you the cardinality the crow's-foot marker is already showing. It says nothing about the business. The relationship exists because a party **places** orders, and that is the fact the schema is there to record.
+
+| Lazy | What it restates | What the business actually says |
+|---|---|---|
+| `belongs to` | the foreign key | `is placed by`, `is owed by`, `is part of` |
+| `has many` | the cardinality marker | `contains`, `journals`, `is broken down into` |
+| `has one` | the key shape | `is realized as`, `is settled via` |
+
+The replacements are not synonyms for the lazy versions. `contains` and `is part of` assert composition, that the child is a constituent of the parent rather than merely pointing at it. `is sold via` and `is realized as` assert that one thing is the concrete form another takes. Those are different claims about the world, and picking between them is modeling work.
+
+
+#### The sentence has to ring true
+
+
+Read the relationship aloud as a sentence, in both directions. If it is not something a person who runs the business would say, and nod at, then either the predicate is wrong or the relationship is.
+
+This is the cheapest correctness check in the model, and it catches things no structural rule can. A predicate you cannot phrase truthfully is usually a relationship that does not belong, or an entity whose purpose you have not settled. When the sentence does ring true, it *is* the business case for the entity carrying it: the reason that table exists, stated in one line, in the language of the people who asked for it.
+
+The reference model reads like this in both directions:
+
+| Relationship | Forward, parent to child | Reverse, child to parent |
+|---|---|---|
+| `SI_Line → SalesInvoice` | SalesInvoice **contains** SI_Line | SI_Line **is part of** SalesInvoice |
+| `SalesOrder → Party` | Party **places** SalesOrder | SalesOrder **is placed by** Party |
+| `SalesInvoice → Party` | Party **owes on** SalesInvoice | SalesInvoice **is owed by** Party |
+| `Business → Party` | Party **is realized as** Business | Business **is a** Party |
+| `SOL_Subscription → Subscription` | Subscription **is sold via** SOL_Subscription | SOL_Subscription **sells** Subscription |
+
+Read the whole diagram with predicates like those and it narrates the business. Read it with `has many` everywhere and it narrates the foreign keys, which you could have got from the DDL.
+
+
+#### Both directions are authored, neither is derived
+
+
+`fwd` reads parent to child. `rev` reads child to parent. ignatius does not invent one from the other, because English does not work that way: the inverse of "is realized as" is "is a", not "is realized as by".
+
+```yaml
+relationships:
+    - target: Identity
+      on:
+          party_id: party_id
+      predicate: { fwd: is realized as, rev: is a }
+```
+
+A plain string sets both directions to the same phrase, which is fine when one reading works both ways (`is a`) and is the right first move when you have not settled the reverse yet.
+
+```yaml
+predicate: is a
+```
+
+Supply only one key of the object form and the other defaults to empty.
+
+The graph draws edges parent to child and labels them with the forward predicate, so the label matches the direction of the line. Hover an entity and every edge touching it re-reads outward from that entity: edges where it is the child flip to the reverse predicate, and edges where it is the parent stay forward. The dictionary, which has no hover, shows the forward predicate and appends the reverse in a muted style when the two differ.
+
+One thing worth carrying past the diagram: once a relationship has a real verb, the foreign key can take its name. A column named for the sentence documents itself, and the schema, the dictionary, and the application code end up speaking the same language as the people who asked for the feature.
+
+
+### Example rows
+
+
+An entity can carry sample instances in `examples:`, a list of row objects keyed by column name.
+
+```yaml
+examples:
+    - party_id: 1
+      type: BUSINESS
+    - party_id: 2
+      type: PERSON
+```
+
+They render as a collapsible table in the entity dialog and the dictionary. Two or three realistic rows are enough. Their job is to make the rules concrete: a sample row that violates a constraint you believe in reveals a modeling error that no structural check can find. Every key must be a real column or PK column, and the live server flags unknown keys with an `entity.example_unknown_column` warning.
+
+
+### Linking entities in prose
+
+
+Double brackets in the body become links.
+
+```markdown
+A **Person** is the specialization of a [[Party]] that is a natural human.
+A customer settles invoices with a [[PaymentMethod|payment method]] on file.
+```
+
+`[[Party]]` links to Party and displays "Party". `[[PaymentMethod|payment method]]` links to PaymentMethod and displays "payment method". In the graph the link opens that entity's dialog; in the dictionary it jumps to its section. The target must match an entity id exactly, case-sensitive. A link to an entity that does not exist renders as muted, non-clickable text and is reported as a `body.unknown_link` finding, so a typo never passes silently.
+
+
+## Key inheritance in practice
+
+
+Here is the pattern the tool is shaped around, taken from the reference model that ships with ignatius.
+
+```
+Party          pk: party_id
+SalesInvoice   pk: party_id, sales_invoice_id
+SI_Line        pk: party_id, sales_invoice_id, line_seq
+```
+
+`SalesInvoice` does not get an independent `invoice_id`. It inherits `party_id` from `Party` and adds its own discriminator. `SI_Line` inherits both and adds a line sequence. Every line item carries its full lineage in its own identity, so the owning party is available without a join, and a line item that belongs to the wrong invoice is not expressible.
+
+Three things fall out of that automatically:
+
+- The edge from `SalesInvoice` to `Party` is **identifying**, because the foreign-key column sits inside the child's primary key.
+- The cardinality is **one-to-many**, because the child has primary-key columns beyond the foreign key.
+- `SalesInvoice` classifies as **dependent**, because it has exactly one identifying parent.
+
+None of that was declared. Changing the key shape changes all three on the next reload.
+
+
+## What gets derived
+
+
+### Cardinality
+
+
+Cardinality comes from the primary-key layout, the relationship type, and foreign-key nullability. There is no `cardinality` field.
+
+- An identifying edge where the child's primary key equals the foreign key exactly is one-to-one.
+- A child with primary-key columns beyond the foreign key is one-to-many.
+- A nullable foreign key makes the parent side optional.
+
+An edge is identifying when its foreign-key columns are part of the child's primary key. That too comes from the key shape, never from a per-edge flag.
+
+
+### Classification
+
+
+Classification comes from how an entity connects to others, applied in this order.
+
+1. **Classifier**, flagged as a reference or classifier entity.
+2. **Subtype**, a member of another entity's subtype cluster.
+3. **Associative**, two or more identifying parents.
+4. **Dependent**, exactly one identifying parent.
+5. **Independent**, none of the above.
+
+Classification sets the node shape, so the diagram reflects structure rather than a label you maintain. The only declaration the parser reads is `reference: true`, which marks a lookup or code table and satisfies rule 1. A legacy `classification: Classifier` does the same thing. Any other `classification:` value is ignored, and no finding reports the mismatch, so a label written by hand drifts silently.
+
+
+### Subtype clusters
+
+
+A basetype declares its members in `subtypes:`, with a discriminator mapping per member.
+
+```yaml
+subtypes:
+    - exclusive: true
+      desc: Every Party is exactly one of Business or Person
+      members:
+          Business:
+              type: PartyType.code.BUSINESS
+          Person:
+              type: PartyType.code.PERSON
+```
+
+Clusters render with diamond joiners between the basetype and its members. An exclusive cluster shows an X in the diamond and needs a discriminator column saying which subtype a basetype row is. An inclusive cluster leaves the diamond empty and needs no discriminator, because several subtypes can coexist for the same row. An exclusive cluster with no discriminator raises `cluster.no_discriminator`.
+
+
+## Lineage: how key inheritance pays off in the viewer
+
+
+A key-inherited entity shares its primary-key ancestry with a whole family. Selecting one should surface the family, and ignatius does that with a lineage spotlight: dotted lines in the dictionary and dotted inferred-upstream rays in the graph.
+
+The rule is precise. A **key edge** is one whose child-side foreign-key columns are all contained in the child's primary key. That is a subset test, not an equality test, which is what makes it correct for both cases:
+
+- A subtype member pointing at its basetype, where the foreign key equals the full primary key.
+- `SalesInvoice → Party`, where `party_id` is a proper subset of `{party_id, sales_invoice_id}`. This is the identifying one-to-many case, and an equality test would miss it.
+
+An entity's lineage is the transitive connected component of that entity in the graph of key edges only, traversed in both directions. Secondary foreign keys are excluded. A classifier reference like `Party → PartyType` is a real relationship but not a shared-key ancestry, so it never pulls an unrelated entity into the spotlight.
+
+Subtype clusters fall out for free, since every member-to-basetype relationship is itself a key edge.
+
+The practical effect: select `SSN` in the reference model and the spotlight reaches `SalesInvoice`, `SI_Line`, `SalesOrder`, `SO_Line`, and `PaymentAllocation`, because all of them carry `party_id` inside a larger key. That is the family that moves together when the identity spine changes. On an all-surrogate schema the same feature has nothing to show, because nothing shares a key.
+
+
+## The two key conventions
+
+
+A model can use either convention, and can mix them per entity. The modeling skill detects which one a model uses from the shape of its existing entities rather than asking you to pick a mode.
+
+| Convention | Primary key shape | Foreign key placement |
+|---|---|---|
+| `key-inherited` | Composite: the parent's primary-key columns plus a local discriminator | Foreign-key columns live inside the child's primary key |
+| `orm-oriented` | A single surrogate `id`, typically integer or uuid | Foreign-key columns sit outside the primary key as plain columns |
+
+ignatius ships three variants of the same data model to compare directly: `key-inherited`, `orm-hybrid`, and `orm-pure`. Serving each in turn is the fastest way to see what the convention costs and buys, because the entities and the business meaning are held constant while only the keys change.
+
+Mixing is legitimate. A transactional spine can inherit keys while a lookup table keeps a surrogate code. Do it deliberately rather than by accident, and record the reason in the entity body.
+
+
+## Groups
+
+
+A group is a markdown file in `groups/` with a label and a color in frontmatter and a description in the body.
+
+```markdown
+---
+label: Identity & Accounts
+color: "#2ea043"
+---
+
+Party identity, classifications, and ID documents.
+```
+
+Groups set a border color and a pastel fill for their entities. They do not affect layout. An entity whose `group` names a file that does not exist renders without a color band and raises an `entity.unknown_group` warning.
+
+
+## Related
+
+
+- [Data flows](/modeling/data-flows) puts these entities to work as data stores in process diagrams.
+- [The case for proper relational design](/guide/relational-design) makes the argument for inherited keys in the database itself.
+- The [`idef1x` skill](https://www.skills.sh/damusix/skills/idef1x) coaches an agent through the methodology itself, separately from ignatius.
+- The [derivation guide](https://github.com/noormdev/ignatius/blob/main/docs/guides/derivation.md) and the [folder format reference](https://github.com/noormdev/ignatius/blob/main/docs/guides/folder-format.md) carry the exhaustive rules.
diff --git a/docs/modeling/index.md b/docs/modeling/index.md
new file mode 100644
index 00000000..817cee48
--- /dev/null
+++ b/docs/modeling/index.md
@@ -0,0 +1,127 @@
+---
+title: Information modeling
+description: Plan the data model before you build it. ignatius turns a folder of markdown into an IDEF1X entity diagram, a searchable data dictionary, and SSADM data flow diagrams.
+---
+
+# Information modeling
+
+
+Most schemas get designed while they are being built. A table appears because a feature needed it, a column gets added because a bug needed it, and the shape of the whole thing only exists in the migration history and in the head of whoever wrote it. By the time anyone can see the model, it is already in production and expensive to change.
+
+[ignatius](https://github.com/noormdev/ignatius) moves that work earlier. It is a planning tool for information modeling: you describe entities, keys, and relationships in markdown files, and it renders them as an interactive diagram you can hand to another person. The binary never connects to a database and never generates DDL. Its output is a picture of what you intend to build, precise enough to argue about before anyone writes SQL.
+
+<!-- Wrapped in a div because `video` is not a CommonMark block-level tag:
+     left bare, markdown-it splits the multi-line element across paragraphs and
+     Vue's SFC parser then rejects the orphaned closing tag. -->
+<div class="demo-video">
+<video src="/video/ignatius.mp4" poster="/video/ignatius-poster.jpg" width="1316" height="858" controls muted playsinline preload="none"></video>
+</div>
+
+Above: a model of an LLM memory database, walked through all three views. The entity dialog, the searchable dictionary with its key-inheritance lineage, and a decomposed process flow where an external LLM agent creates and files artifacts.
+
+
+## What it produces
+
+
+One folder of markdown files drives three views of the same model.
+
+| View | What it shows |
+|---|---|
+| Data Graph | An IDEF1X entity-relationship diagram in crow's-foot notation. Pan, zoom, click an entity to open its full definition. |
+| Data Dictionary | Every entity, process, external, and store in one searchable reference page. |
+| Data Flows | SSADM data flow diagrams showing how processes move data between people, the database, and everything else. |
+
+The diagrams are generated, never drawn. You write the structure as text, and ignatius derives the cardinality, the entity classification, and the subtype clusters from the key shape you described. Change a foreign key and the notation updates on the next reload. A model that lives in markdown diffs like code, reviews like code, and cannot drift from a picture somebody drew once in a diagramming app.
+
+
+## Why a web instead of a list
+
+
+A table list tells you what exists. It does not tell you how anything connects, or why any of it is there.
+
+The graph gives you the web: which entities hang off which, where identity comes from, which clusters are subtypes of a common basetype. Each entity carries a prose body explaining what it is and what business function it serves, so the answer to "why does this table exist" lives next to the table. Each entity also carries example rows. Two or three realistic instances make the rules concrete, and a sample row that violates a constraint you believed in reveals a modeling error no structural check will catch.
+
+You make better decisions with a full view of the thing you are about to build. That is the whole argument for doing this before the schema exists rather than after.
+
+
+## Written for people and for models
+
+
+The source is markdown with YAML frontmatter, which suits both readers.
+
+A stakeholder gets the rendered app: a diagram they can explore, a dictionary they can search, and prose that explains the business meaning rather than the storage layout. `ignatius export` writes all three views into one self-contained HTML file with no external dependencies, so a reviewer opens it from `file://` and needs nothing installed.
+
+A coding agent gets plain text it can read and write directly. ignatius comes with the [`noorm-modeling` skill](/modeling/modeling-skill) for Claude Code, which authors entity and flow files through guided Q&A and verifies each one with `ignatius validate` before moving on.
+
+
+## The workflow
+
+
+Model first, get agreement, then build.
+
+1. **Model.** Describe the entities and the processes in markdown, either by hand or through the modeling skill.
+2. **Review.** Serve the model or export it to HTML and walk stakeholders through the graph and the flows. Arguments about the shape of the data are cheap here and expensive later.
+3. **Build.** Once the model is agreed, hand it to your agent as the specification. The files that describe the model are the same files the LLM reads to write the schema.
+
+noorm is the other half of that last step. ignatius describes what you intend to build. noorm builds it, versions it, and keeps every environment in sync. The two share a bias: your schema belongs in files you own, not in an object model a tool derived for you.
+
+
+## Why a separate tool
+
+
+noorm already explores schemas and runs SQL, so it is fair to ask why modeling is a second binary instead of a `noorm model` subcommand. Three reasons, and they all come back to ignatius being useful at a moment when noorm is not.
+
+**It never touches a database.** ignatius carries no driver and emits no DDL. Its value is being usable before the database exists, which is exactly the moment a tool that requires a connection has nothing to offer. Putting the planning step inside noorm would gate it behind the thing you have not built yet.
+
+**It does not need noorm.** Nothing in the format is noorm-specific: markdown in, IDEF1X and SSADM diagrams out, with no dialect anywhere in the pipeline. A team on Prisma, ActiveRecord, or hand-written migrations gets the same thing from it. Making it a subcommand would shrink its audience to noorm users and buy nothing.
+
+**The audiences differ.** `ignatius export` produces a file for the person approving a design, not the person deploying a schema. That reader is not going to install a schema and change manager to look at a diagram.
+
+There is a practical consequence worth knowing as you read: the two ship on their own cadences from their own repositories. That is why these pages carry the narrative and link out to the ignatius repo for the exhaustive rule catalogs rather than copying them here, where they would drift out of date.
+
+
+## Two notations, two questions
+
+
+ignatius answers a different question in each of its diagram views.
+
+**IDEF1X** answers "what is the data, and how is it identified". It is the premise the entity side is built on, which is why key inheritance gets first-class treatment: identifying relationships, compound keys that carry their lineage, and subtype clusters with exclusive or inclusive discriminators. See [Entities and key inheritance](/modeling/entities).
+
+**SSADM data flow diagrams** answer "who touches the data, and where does it live". Processes, external actors, and data stores. Stores are not only tables. A cache, a log file, a queue, a paper form, and a document all appear as first-class stores, so the diagram shows where data rests rather than only the part of it that reached a database. See [Data flows](/modeling/data-flows).
+
+
+## Where the name comes from
+
+
+ignatius is named for Derek Ignatius Asirvadem, who mentored me for a couple of years and introduced me to IDEF1X.
+
+Studying it and then practising it convinced me there is no higher standard for modeling data. The industry mostly skips modeling and goes straight to building. Modeling first solves something like 80% of the problems up front, and it produces months of valid programming work before anyone opens an editor.
+
+The other 20% is real and worth naming: once you start building, you **do** find problems in the model. That is the part that drifts. What matters is when you find it. While nothing is physically committed to the system yet, changing the model is cheap. Once it is code, it is not. Modeling holds that cheap window open longer, and an agent working from a written model holds it open longer still.
+
+Before ignatius I drew models in OmniGraffle, on Derek's recommendation. Two things broke that. My own obsession with perfect lines and perfect names turned drawing into the bottleneck, and there was no way to tell an LLM "this is the relationship between these two entities" from a picture. So the model moved into markdown, where both problems go away. The layout is generated rather than drawn, and the source is text an agent can read and write.
+
+None of these tools would exist without his guidance. ignatius is a tribute to him.
+
+
+## Next steps
+
+
+<div class="next-steps">
+
+[**Installation**](/modeling/installation)
+Install the binary and the modeling skill.
+
+[**Entities and key inheritance**](/modeling/entities)
+The entity format, what gets derived, and the two key conventions.
+
+[**Data flows**](/modeling/data-flows)
+Processes, externals, stores, and sub-diagrams.
+
+[**Reverse-engineering**](/modeling/reverse-engineering)
+Extract a model from a database you already run.
+
+[**Best practices**](/modeling/best-practices)
+How to get a model worth showing to a stakeholder.
+
+</div>
diff --git a/docs/modeling/installation.md b/docs/modeling/installation.md
new file mode 100644
index 00000000..c17f9ecf
--- /dev/null
+++ b/docs/modeling/installation.md
@@ -0,0 +1,163 @@
+---
+title: Installing ignatius
+description: Install the ignatius binary and the noorm-modeling skill, then serve, validate, and export your first model.
+---
+
+# Installing ignatius
+
+
+ignatius is a single self-contained binary with no runtime dependency. It runs on machines without Bun or Node installed.
+
+
+## Install script
+
+
+The script detects your operating system and architecture, downloads the matching binary from the [latest release](https://github.com/noormdev/ignatius/releases/latest), verifies its checksum, and puts it on your `$PATH`.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/noormdev/ignatius/main/install.sh | sh
+```
+
+It installs to `/usr/local/bin` when that directory is writable and `$HOME/.local/bin` otherwise. Two environment variables override the defaults:
+
+- `IGNATIUS_INSTALL_DIR=/some/dir` installs somewhere else.
+- `IGNATIUS_VERSION=v0.2.0` pins a release tag instead of taking the latest.
+
+Verify with `ignatius --help`.
+
+
+## Download a release
+
+
+To install by hand, or on Windows, take the binary for your platform from the [latest release](https://github.com/noormdev/ignatius/releases/latest).
+
+```bash
+# macOS arm64
+curl -L -o ignatius https://github.com/noormdev/ignatius/releases/latest/download/ignatius-darwin-arm64
+chmod +x ignatius
+sudo mv ignatius /usr/local/bin/
+
+# Linux x64
+curl -L -o ignatius https://github.com/noormdev/ignatius/releases/latest/download/ignatius-linux-x64
+chmod +x ignatius
+sudo mv ignatius /usr/local/bin/
+```
+
+Windows users take `ignatius-windows-x64.exe` from the same page. Each release includes `checksums.txt` for verifying a manual download with `shasum -a 256 -c`.
+
+
+## From source
+
+
+ignatius builds with [Bun](https://bun.com).
+
+```bash
+git clone https://github.com/noormdev/ignatius.git
+cd ignatius
+bun install
+bun run build:cli
+```
+
+That produces `./dist/ignatius`.
+
+
+## Staying current
+
+
+```bash
+ignatius version          # print the installed version
+ignatius update           # check for a newer release, then prompt
+ignatius update --check   # report only, never install
+ignatius update --yes     # install without prompting, for scripts
+```
+
+`update` downloads the binary for your platform, verifies its checksum against the release `checksums.txt`, and replaces the running executable in place. That needs write access to the installed binary, so a binary in `/usr/local/bin` wants `sudo ignatius update --yes`. Outside a terminal it reports the available version and exits without installing unless you pass `--yes`. Windows binaries cannot replace themselves while running, so on Windows the command points you at the release download instead.
+
+
+## The modeling skill
+
+
+To author models from Claude Code, install the `noorm-modeling` skill with the [`skills`](https://www.npmjs.com/package/skills) CLI.
+
+```bash
+npx skills add https://github.com/noormdev/ignatius --skill noorm-modeling
+```
+
+That adds the skill to the current project's `.claude/skills/`. Add `-g` to install it globally for every project on the machine. Reload skills in Claude Code and `/noorm-modeling` becomes available. See [The modeling skill](/modeling/modeling-skill) for what each mode does.
+
+
+## Serve a model
+
+
+Point ignatius at a folder that contains an `ignatius.yml` file.
+
+```bash
+ignatius serve path/to/your/models --port 3000
+```
+
+Editing any `.md` or `.yaml` file under that folder pushes an update to the open browser tab over server-sent events, so the diagram reloads without a refresh.
+
+The path argument is optional. With no path, ignatius searches up and down from the current directory for a model root. When it finds more than one it prompts you with a list in a terminal, or takes `--model <key>` to skip the prompt. In a non-interactive shell an ambiguous run exits with an error and prints the available keys rather than hanging. The search skips `node_modules`, `.git`, `dist`, `tmp`, `trash`, `.worktrees`, `.claude`, and any path segment starting with `_`.
+
+The default port is 3000. When that port is taken, ignatius counts up to the next free one and asks which to use, with the free port as the default. Run non-interactively it advances automatically and prints the port it settled on. Pass `-o` to open the app in your browser once the server binds, on whichever port it ended up with.
+
+The app has three views, switched without a page reload and reflected in the URL hash: Graph (`#view=graph`), Dictionary (`#view=dict`), and Flows (`#view=flow`). Back, forward, and deep links all work.
+
+
+## Validate a model
+
+
+```bash
+ignatius validate [path] [--model <key>]
+```
+
+`validate` checks the model and reports findings without writing anything. It prints each finding to stderr and a one-line summary to stdout, then exits `1` when the model has errors and `0` otherwise. Warnings alone do not fail the command. When the model has a `flows/` directory the flow rules run too.
+
+That exit-code contract makes it usable as a CI gate. Findings come in two classes: a warning still renders the entity with a badge, while an error omits the broken reference (one edge, one cluster, one unparseable file) and names the omission in a banner. A typo in one of three foreign keys strips that edge and keeps the entity. The [full rule catalog](https://github.com/noormdev/ignatius/blob/main/docs/guides/validation.md) lists every rule and its class.
+
+
+## Export a model
+
+
+```bash
+ignatius export [path] -o model.html [--theme light|dark] [--model <key>]
+```
+
+`export` writes all three views into one HTML file with no external dependencies. View switching, dictionary search, the entity dialog, the theme toggle, and node-position persistence all work offline from `file://`. `-o` is required.
+
+This is the artifact you send to someone who will not install anything. Commit it next to the model, attach it to a ticket, or mail it to the stakeholder whose sign-off you need.
+
+
+## Keyboard shortcuts
+
+
+Single-key shortcuts work while no text field is focused and no modifier is held.
+
+| Key | Action |
+|---|---|
+| `g` | Switch to the Data Graph |
+| `d` | Switch to the Dictionary |
+| `f` | Switch to the Data Flows |
+| `l` | Toggle graph layout, organic or hierarchical (Graph view) |
+| `b` | Toggle dictionary lens, read or browse (Dictionary view) |
+| `/` | Focus the search bar |
+| `?` | Open the help overlay for the current view |
+| `↑` `↓` `←` `→` | Pan the canvas (Graph and Flows); hold `Shift` for a longer step |
+
+Zoom and search also answer to modifier chords. Those work even while a text field is focused, because the chords are not typed characters, and zoom acts on the diagram canvas rather than the browser page.
+
+| Input | Action |
+|---|---|
+| `Cmd`/`Ctrl` + `=` | Zoom in |
+| `Cmd`/`Ctrl` + `-` | Zoom out |
+| `Cmd`/`Ctrl` + `0` | Fit the diagram to the screen |
+| `Cmd`/`Ctrl` + `k` | Focus the search bar |
+| Trackpad pinch | Zoom toward the pointer |
+
+
+## Next steps
+
+
+- [Entities and key inheritance](/modeling/entities) covers the folder format and the entity file.
+- [Data flows](/modeling/data-flows) covers processes, externals, and stores.
+- [The modeling skill](/modeling/modeling-skill) covers authoring from Claude Code.
diff --git a/docs/modeling/modeling-skill.md b/docs/modeling/modeling-skill.md
new file mode 100644
index 00000000..a1576d5c
--- /dev/null
+++ b/docs/modeling/modeling-skill.md
@@ -0,0 +1,86 @@
+---
+title: The modeling skill
+description: /noorm-modeling authors ignatius entities and data flow diagrams through guided Q&A in Claude Code, and verifies each file with ignatius validate.
+---
+
+# The modeling skill
+
+
+`/noorm-modeling` is a Claude Code skill that authors a model through question and answer, then checks its own work. It writes one entity, a data flow diagram, a fresh model skeleton, or a full discovery session that works the model out from how your business runs.
+
+The skill exists because the hard part of modeling is not the YAML. It is knowing which questions to ask, in which order, and noticing when an answer contradicts an earlier one. The skill carries that interview structure, and you supply the domain knowledge.
+
+**Prerequisites:** Claude Code with skill support, and the `ignatius` binary on your `$PATH` or built locally with `bun run build:cli`.
+
+
+## Install
+
+
+```bash
+npx skills add https://github.com/noormdev/ignatius --skill noorm-modeling
+```
+
+That adds `noorm-modeling` to the current project's `.claude/skills/`. Add `-g` to install it globally for every project on the machine. Reload skills in Claude Code and `/noorm-modeling` becomes available.
+
+
+## Modes
+
+
+| Invocation | What it does |
+|---|---|
+| `/noorm-modeling entity` | Interactive Q&A to author one entity file |
+| `/noorm-modeling model` | Bootstrap a new model skeleton: `ignatius.yml`, group files, directories |
+| `/noorm-modeling flow` | Interactive Q&A to author a [data flow diagram](/modeling/data-flows) |
+| `/noorm-modeling discover` | Socratic interview that works the model out from how your business runs, generating entities and flows |
+| `/noorm-modeling` | Prompts you to choose a mode |
+
+
+## Choosing between flow and discover
+
+
+`flow` and `discover` are two doors into the same artifacts.
+
+Pick `flow` when you can already name your processes. It walks the structure step by step: processes as verbs, externals, the decision between a `db:` store and a `kind:` store, the data each flow carries, sample rows, and the business narrative.
+
+Pick `discover` when you know what the business does but have not decomposed it yet. The skill interviews you in plain language, derives the entities your processes require, writes those first, then writes the flows that reference them. When a real system already exists, whether a database, a schema dump, a codebase, or an API, `discover` reads it instead of interviewing you and then walks you through the judgment calls it cannot infer. To point it at a live database, see [Reverse-engineering an existing database](/modeling/reverse-engineering).
+
+Both modes always produce example data. Every entity gets sample rows and every process gets input and output tables, because concrete instances expose wrong rules that pass every structural check.
+
+
+## Convention detection
+
+
+The skill works out which key convention a model uses from the shape of its existing entities rather than asking you to choose a mode up front, and a model can mix both styles per entity.
+
+| Convention | Primary key shape | Foreign key placement |
+|---|---|---|
+| `key-inherited` | Composite: parent primary-key columns plus a local discriminator | Inside the child's primary key |
+| `orm-oriented` | A single surrogate `id`, typically integer or uuid | Outside the primary key, as plain columns |
+
+You never set `classification` or `identifying` by hand in either convention. The parser derives both from the key shape you describe. See [what gets derived](/modeling/entities#what-gets-derived).
+
+
+## The verification loop
+
+
+After writing each file the skill runs `ignatius validate <model-root>` and parses the findings from stderr. Findings are reported with fix hints, and you can ask the skill to revise and re-run, up to five attempts. A clean run with no findings confirms the file is valid.
+
+This is the part that makes agent-authored models trustworthy. The skill is not asked to be right on the first try. It is asked to converge against a linter that checks unknown targets, dangling foreign-key columns, missing discriminators, unknown columns in flow contracts, and unbalanced decompositions.
+
+
+## From model to schema
+
+
+A validated model is a specification, and the same markdown a stakeholder reviewed is what the agent reads to build.
+
+Once the model is agreed, point Claude Code at the model root and ask it to write the SQL. The entity files carry the keys, the columns, the relationships, and the prose explaining what each one is for, which is more context than a schema request usually gets. From there, [noorm](/getting-started/installation) takes over: SQL files in directories, `noorm run build` to build a fresh database, and changes for existing ones.
+
+The division of labor is worth stating plainly. ignatius owns the decision about what the data is. noorm owns building and versioning it. Neither tool reaches into the other's job, and both keep the source of truth in files you own.
+
+
+## Related
+
+
+- [Entities and key inheritance](/modeling/entities) for the format the skill writes.
+- [Data flows](/modeling/data-flows) for the diagram format.
+- [Best practices](/modeling/best-practices) for how to review what the skill produces.
diff --git a/docs/modeling/reverse-engineering.md b/docs/modeling/reverse-engineering.md
new file mode 100644
index 00000000..70240365
--- /dev/null
+++ b/docs/modeling/reverse-engineering.md
@@ -0,0 +1,189 @@
+---
+title: Reverse-engineering an existing database
+description: Point an agent at a database you already run and have it extract an ignatius model, using noorm's MCP server for read-only schema access.
+---
+
+# Reverse-engineering an existing database
+
+
+Most databases worth modeling already exist. The schema is in production, the reasoning behind it left with someone two jobs ago, and the only description of it is the DDL.
+
+You do not have to model that by hand. noorm exposes the schema to a coding agent over MCP, and the [`noorm-modeling` skill](/modeling/modeling-skill) knows how to turn what it reads into entity and flow files. Your job is to set up the access, keep it read-only, and review what comes back.
+
+The result is an ignatius model of the system you already run: a diagram to hand to people, a dictionary of what every table is for, and a base to plan the next change against.
+
+
+## Where this sits in IDEF1X
+
+
+Extraction is not a detour around the methodology. It is a recognized path inside it. IDEF1X calls this the **bottom-up** approach, inferring a logical model from the physical artifacts that already exist, and the full round trip of reverse-engineer, adjust for new requirements, then forward-engineer is **re-engineering**.
+
+The discipline is also specific about how far bottom-up gets you, which is worth knowing before you start rather than after. A *data model* describes a physical database. An *information model* describes the logical requirements a system satisfies. Reverse-engineering climbs from the first toward the second in levels:
+
+| Level | What you get | What it is worth |
+|---|---|---|
+| 1 | Current-system documentation, a physical model | Guaranteed only to show what **is** |
+| 2 | Application-level logical model | The requirements the system currently satisfies, with no claim about whether they are right |
+| 3 | Business-level model | A basis for future design, and unreachable without the business participating directly |
+
+An agent with schema access reaches level 1 quickly and gets a good way into level 2. It cannot reach level 3 on its own, because the information at that level was never in the database. It is in the heads of the people who run the business, and the only way out is to ask them.
+
+The IDEF1X literature is blunt about the risk, and the warning is the reason this page ends with a review step rather than a success message: **a model of what you have is not a model of what you want.** Assumptions compound as you climb the levels, and their source is the past, mistakes included. That is also why the skill records anti-patterns instead of quietly correcting them. Faithful first, better second, with the "better" being a conversation you have afterward rather than something extraction decides for you.
+
+The [`idef1x` skill](https://www.skills.sh/damusix/skills/idef1x) carries the methodology itself if you want an agent applying it alongside you.
+
+
+## What you need
+
+- noorm installed, with a config that connects to the database ([installation](/getting-started/installation))
+- ignatius installed ([installation](/modeling/installation))
+- The `noorm-modeling` skill, and optionally the noorm skill for SDK and CLI conventions
+- An agent harness that speaks MCP, such as Claude Code or Cursor
+
+
+## 1. Create the modeling space
+
+
+A model root is any folder with an `ignatius.yml` in it. Let the skill scaffold one:
+
+```bash
+/noorm-modeling model
+```
+
+That writes `ignatius.yml`, the group files, and the directories. To do it by hand, a one-line `ignatius.yml` is a valid model root:
+
+```bash
+mkdir -p models/legacy && echo "name: Legacy Schema" > models/legacy/ignatius.yml
+```
+
+Put it in the repository whose schema it describes, so the model and the code stay in one history.
+
+The rest of this page refers to that folder as `models/legacy`. Substitute wherever yours actually landed, or leave the path off entirely: `serve`, `export`, and `validate` all take the model root as an optional argument and find it by searching up and down from the current directory when you omit it.
+
+
+## 2. Connect noorm over MCP
+
+
+noorm runs an MCP server over stdio. Generate the agent's config:
+
+```bash
+noorm mcp init                  # Claude Code, writes .mcp.json
+noorm mcp init --agent cursor   # Cursor, writes .cursor/mcp.json
+```
+
+The agent picks up the server on next launch and gets two tools: `noorm_help` to list commands and `run_noorm_cmd` to execute them. The schema explorer, the SQL runner, and config management all arrive through those.
+
+Make sure the config you want the agent reading is the active one, and that it points at the database you mean. Reverse-engineering staging when you meant production produces a confident model of the wrong thing.
+
+
+## 3. Keep the config read-only
+
+
+Every config carries a role per channel, `access: { user, agent }`, and the `agent` role governs what a coding agent can do regardless of whether it comes in over MCP or shells out to the `noorm` binary. noorm resolves the channel from the harness that spawned it, so an agent refused over MCP cannot route around the refusal on the command line.
+
+| Role | What the agent can do |
+|---|---|
+| `viewer` | Explore schema, run read-only SQL (`SELECT`, `SHOW`, `DESCRIBE`). `EXPLAIN` inherits the class of the statement it wraps, so `EXPLAIN ANALYZE DELETE ...` is a write and is denied |
+| `operator` | Adds `INSERT`/`UPDATE`/`DELETE`; destructive commands stay out of reach |
+| `admin` | Adds DDL, change and run commands, and vault writes. The irreversible operations (drop, teardown, truncate, config rewrite, vault propagate, force-unlock) are confirmation-gated, and a confirmation collapses to a denial on the agent channel |
+| `false` | The config is invisible on that channel |
+
+`viewer` is all reverse-engineering needs, and it is already the default: a config that never declared `access` gets `{ user: 'admin', agent: 'viewer' }`. So this step is usually a check rather than a change. Confirm it in `noorm ui` under Config → Edit, and lower it back to `viewer` if someone raised it for other work.
+
+Raw SQL is classified by what the statement does rather than which command asked, so an agent on `viewer` gets a `SELECT` through and a same-shaped `INSERT` denied.
+
+::: warning Roles prevent accidents, not attacks
+The `agent` role is a guardrail against a mistake, not a security boundary. It stops an agent from doing damage it never meant to do, which is the realistic failure. It does not stop one that has been talked into it: `NOORM_CHANNEL` is an environment variable, so anything able to influence the agent's instructions or its environment can reach around the role.
+
+That is worth weighing here specifically, because reverse-engineering points an agent at a large amount of text you did not write. Table comments, column descriptions, and stored procedure bodies are all content a prompt injection can ride in on.
+
+So for a database you care about, connect noorm with a database user that holds only `SELECT` and catalog permissions. Then the role is the second line of defense rather than the only one, and an instruction that gets past it still cannot write anything.
+:::
+
+
+## 4. Give the database user catalog access
+
+
+The explorer reads your database's system catalogs. Which ones depends on the dialect:
+
+| Dialect | Catalog noorm reads |
+|---|---|
+| PostgreSQL | `information_schema` views (`columns`, `table_constraints`, `key_column_usage`, `referential_constraints`, `parameters`) |
+| MySQL | `information_schema` views (`columns`, `key_column_usage`, `referential_constraints`, `routines`, `parameters`) |
+| SQL Server | `sys` catalog views (`sys.columns`, `sys.foreign_keys`, `sys.foreign_key_columns`, `sys.index_columns`) |
+| SQLite | `sqlite_master` and `PRAGMA` (file access, no grants) |
+
+This is the step that quietly ruins a model, because a permissions gap does not raise an error. It returns fewer rows.
+
+PostgreSQL filters the information schema by privilege: "Only those tables and views are shown that the current user has access to (by way of being the owner or having some privilege)." SQL Server behaves the same way through metadata visibility, where "the visibility of metadata is limited to securables that a user either owns or on which the user has been granted some permission," and a user with no permission on a table gets an empty result set rather than a denial.
+
+An agent reading through an under-privileged user therefore produces a model that looks finished and is silently missing tables. Grant catalog access before you start:
+
+```sql
+-- PostgreSQL: visibility follows privilege
+GRANT USAGE ON SCHEMA public TO modeler;
+GRANT SELECT ON ALL TABLES IN SCHEMA public TO modeler;
+
+-- MySQL: same idea, per schema
+GRANT SELECT ON mydb.* TO 'modeler'@'%';
+
+-- SQL Server: metadata visibility without data access
+GRANT VIEW DEFINITION TO modeler;
+```
+
+Then check the count. Ask the agent, or run it yourself, for the table list noorm sees and compare it against what you know is there. A mismatch here is cheaper to catch now than after the model is written.
+
+
+## 5. Ask the agent to reverse-engineer
+
+
+Launch the harness and point it at both the database and the model root:
+
+```
+/noorm-modeling discover
+```
+
+`discover` interviews you when nothing exists yet. When a real system is available it reads that instead, and interviews you only about the judgment calls the schema cannot answer. Tell it where the model root is and that noorm's MCP server is connected.
+
+Code is worth offering alongside the schema. Foreign keys give the agent your entities and relationships, but only the handlers, jobs, and stored procedures that touch the data can give it the processes for the [data flow diagrams](/modeling/data-flows). A `SELECT` inside a request handler is an input flow with a column list; an `INSERT` is an output flow. Point the agent at the repository and the flows come out at column level rather than as guesses.
+
+
+## 6. What a good extraction does
+
+
+The skill's method is worth knowing, because it is what you review against.
+
+**It reads rather than invents.** Entities come from tables, attributes from columns with nullability preserved, relationships from foreign-key constraints, and subtype clusters from tables whose whole primary key equals their parent's. Whether an edge is identifying is derived from the key shape, never declared.
+
+**It keeps the source's names.** `sales_orders` stays `sales_orders`. The entity id is what every relationship target, wiki link, and `db:` token has to match, so renaming during extraction breaks the correspondence with the real system. A rename is a decision to surface, not a cleanup to perform quietly.
+
+**It detects your key convention instead of imposing one.** A composite primary key containing a foreign key reads as `key-inherited`; a lone surrogate `id` with foreign keys outside the key reads as `orm-oriented`. Mixed schemas stay mixed. See [the two key conventions](/modeling/entities#the-two-key-conventions).
+
+**It records anti-patterns rather than fixing them.** Faithful first, better second. A junk-drawer table or a surrogate key where the real identity is composite gets captured as it is, then raised with you as a question. Silent improvement during extraction produces a model of a database you do not have.
+
+**It grounds the model in real rows.** Sample data from the live system makes the best examples, which is why every entity and process should carry some. Mask anything sensitive before it lands in a file you commit.
+
+
+## 7. Verify and review
+
+
+```bash
+ignatius validate models/legacy      # or just `ignatius validate` from inside the project
+ignatius serve models/legacy -o
+```
+
+`validate` exits `1` on errors and `0` otherwise, so it works as a gate. A clean run means the model is internally consistent. It does not mean the model is right, and the two failures worth hunting are ones no linter catches: a table the agent could not see, and a purpose it invented because the schema could not tell it one.
+
+Read the entity bodies with that in mind. Any entity whose description restates its columns rather than explaining what it is for is a question the agent could not answer from the schema, and the answer is in your head or nobody's. Those paragraphs are the part of the model worth the most later, and the part only you can supply.
+
+This is the climb from level 2 to level 3, and it is the work reverse-engineering cannot do for you. An extracted model tells you what the database is. Turning that into what the business means, and then into what it should be, takes the people who run it. Serve the model, walk them through it, and let the arguments start.
+
+
+## Related
+
+
+- [Entities and key inheritance](/modeling/entities)
+- [Data flows](/modeling/data-flows)
+- [The modeling skill](/modeling/modeling-skill)
+- [MCP (AI agent integration)](/guide/automation/mcp) for the server itself
+- [Access roles](/guide/environments/configs#access-roles) for channel detection and the `NOORM_CHANNEL` override
diff --git a/docs/public/video/ignatius-poster.jpg b/docs/public/video/ignatius-poster.jpg
new file mode 100644
index 00000000..ff1bc2fe
Binary files /dev/null and b/docs/public/video/ignatius-poster.jpg differ
diff --git a/docs/public/video/ignatius.mp4 b/docs/public/video/ignatius.mp4
new file mode 100644
index 00000000..00f92cd7
Binary files /dev/null and b/docs/public/video/ignatius.mp4 differ
diff --git a/docs/reference/sdk.md b/docs/reference/sdk.md
index fdc31166..b354d83c 100644
--- a/docs/reference/sdk.md
+++ b/docs/reference/sdk.md
@@ -52,6 +52,7 @@ interface CreateContextOptions {
     requireTest?: boolean;    // Refuse if config.isTest !== true
     channel?: Channel;        // 'user' (default) or 'agent' — which access role applies
     stage?: string;           // Stage name for stage defaults
+    yes?: boolean;            // Pre-confirm operations a policy 'confirm' cell would block
 }
 
 const ctx = await createContext<MyDatabase>({
@@ -69,9 +70,14 @@ const ctx = await createContext<MyDatabase>({
 | `requireTest`    | `boolean` | Throws `RequireTestError` if config doesn't have `isTest: true`. |
 | `channel`        | `Channel` | Which caller channel this context represents for access-policy checks. Defaults to `'user'`. A destructive operation the config's role denies — or that resolves to "requires confirmation," which the SDK can't prompt for — throws `ProtectedConfigError`. |
 | `stage`          | `string`  | Stage name for inheriting stage defaults.                        |
+| `yes`            | `boolean` | Pre-confirms operations that a policy "requires confirmation" cell would otherwise block, the programmatic equivalent of the CLI's `--yes`. Defaults to `false`. Only meaningful on the `user` channel: on `agent`, confirmation collapses to denial before `yes` is read, so an agent cannot use it to pass a gate meant for a human. |
+
+There is no `connection` option. Connection details come either from a stored config or, when `NOORM_CONNECTION_DIALECT` and `NOORM_CONNECTION_DATABASE` are set, from the environment — in which case `createContext()` needs no `.noorm/` directory and no identity at all. That is the mode to use in production; see [Deploying an Application](/guide/deployment).
 
 > Access is per-config, not per-context: each config declares `access: { user, agent }` (roles `viewer`/`operator`/`admin`, or `agent: false` to hide the config from agents entirely, over MCP and the CLI alike). `channel` tells `createContext` which half of that grant to enforce — see [Access Roles](/guide/environments/configs#access-roles).
 
+The gate sits at the core seam, so it applies to every method on `ctx.noorm.run`, `.db`, `.changes`, `.lock.forceRelease`, `.vault`, `.secrets`, `.templates`, `.transfer`, and `.dt.importFile`. Raw `ctx.kysely` queries are not gated. Four permissions require confirmation even for `admin` (`db:truncate`, `db:teardown`, `vault:propagate`, `lock:force`), so `ctx.noorm.db.truncate()` on an admin config still throws `ProtectedConfigError` unless the context was created with `yes: true`.
+
 
 ## Top-Level Context Properties
 
@@ -86,14 +92,19 @@ const ctx = await createContext<MyDatabase>({
 ## Lifecycle Methods
 
 
-### connect()
+### connect(retryOptions?)
 
-Establishes the database connection.
+Establishes the database connection. Calling it on an already-connected context is a no-op.
 
 ```typescript
 await ctx.connect();
+
+// Fail fast instead of hanging on an unreachable database.
+await ctx.connect({ retries: 1, delay: 0 });
 ```
 
+`retryOptions` is `ConnectionRetryOptions`: `{ retries?: number; delay?: number; backoff?: number }`, defaulting to `3` attempts, `1000`ms delay, and a `2x` backoff multiplier. Retries cover transient failures (`ECONNREFUSED`, `ETIMEDOUT`); authentication failures and missing drivers fail on the first attempt.
+
 
 ### disconnect()
 
@@ -130,6 +141,34 @@ const result = await ctx.transaction(async (trx) => {
 ```
 
 
+## Impersonation
+
+
+### impersonate(username, fn?)
+
+Run queries as a different database principal. The SDK borrows one connection from the pool, switches identity on it, and hands you a scope whose `kysely`, `proc`, `func`, `tvf`, and `transaction` all route through that connection.
+
+Supported on MSSQL (`EXECUTE AS USER` / `REVERT`) and PostgreSQL (`SET ROLE` / `RESET ROLE`). MySQL and SQLite throw `ImpersonationError`, as does a username containing anything outside alphanumerics, `_`, `@`, `.`, `-`, and `\`.
+
+```typescript
+import { ImpersonationError, type ImpersonatedScope } from '@noormdev/sdk';
+
+// Callback mode: reverts on the way out, including when the callback throws.
+const rows = await ctx.impersonate('app_readonly', async (scope) => {
+    return scope.kysely.selectFrom('users').selectAll().execute();
+});
+
+// Explicit mode: you own the lifecycle.
+const scope = await ctx.impersonate('app_readonly');
+const users = await scope.kysely.selectFrom('users').selectAll().execute();
+await scope.revert();
+```
+
+Explicit mode holds a pooled connection until you call `revert()`. `ctx.disconnect()` releases any scope you never reverted, so a forgotten `revert()` cannot deadlock shutdown, but it does keep a connection out of the pool until then. Prefer callback mode unless you need the scope to outlive one function.
+
+An `ImpersonatedScope` carries no `noorm` namespace and no lifecycle methods. Management operations stay on `ctx.noorm`, running as the context's own principal.
+
+
 ## Stored Procedures, Functions & TVFs
 
 Type-safe helpers for calling stored procedures, database functions, and table-valued functions. Define your signatures as interfaces, then pass them as generics to `createContext`:
@@ -190,6 +229,10 @@ const custom = await ctx.proc<'get_users', CustomUser>('get_users', { department
 
 **Throws** on SQLite (no stored procedure support).
 
+Procedure, function, and column names are quoted per dialect (`"name"` on PostgreSQL, `[name]` on MSSQL, `` `name` `` on MySQL), so mixed-case and reserved-word names survive. A schema-qualified name splits on the first `.` and each half is quoted separately.
+
+On PostgreSQL, `proc()` falls back to a function call when `CALL` reports the target is not a procedure (SQLSTATE `42809` or `42883`). The SDK retries as `SELECT * FROM name(...)`, so `proc()` reaches both `CREATE PROCEDURE` and `CREATE FUNCTION` objects.
+
 
 ### Parameter handling and NULL semantics
 
@@ -381,13 +424,15 @@ The SQL builders validate before generating SQL:
 
 ### func(name, params?, column)
 
-Call a database function and return the scalar result. Generates `SELECT name(...) AS column`. Named params are only supported on PostgreSQL; other dialects fall back to positional.
+Call a database function and return the scalar result. Generates `SELECT name(...) AS column`, except on MSSQL with named params, where T-SQL has no named-argument form for `SELECT` and the SDK uses `EXEC @var = name` instead. MySQL rejects named params outright.
 
 | Dialect    | Named Params                                   | Positional               | No Params              |
 | ---------- | ---------------------------------------------- | ------------------------ | ---------------------- |
 | MSSQL      | `EXEC @var = name @k = $1; SELECT @var AS col` | `SELECT name($1) AS col` | `SELECT name() AS col` |
 | PostgreSQL | `SELECT name(k => $1) AS col`                  | `SELECT name($1) AS col` | `SELECT name() AS col` |
-| MySQL      | `SELECT name($1) AS col` (positional fallback) | `SELECT name($1) AS col` | `SELECT name() AS col` |
+| MySQL      | throws (pass an array instead)                 | `SELECT name($1) AS col` | `SELECT name() AS col` |
+
+Passing an object to `func()` on MySQL throws `MySQL does not support named parameters in function calls. Use positional parameters (array) instead.` This is the one place where a params object is not silently reordered into positional form: `proc()` on MySQL does flatten an object to `Object.values()` order, which is why `func()` refuses rather than guessing.
 
 ```typescript
 // Named params + column alias — return type inferred from tuple
@@ -415,10 +460,12 @@ const custom = await ctx.func<'calc_total', { amount: number }>('calc_total', {
 
 Call a table-valued function and return the result set rows. Supported on MSSQL and PostgreSQL only.
 
-| Dialect    | Named Params                         | Positional                | No Params               |
-| ---------- | ------------------------------------ | ------------------------- | ----------------------- |
-| MSSQL      | `SELECT * FROM name(@k = $1)`       | `SELECT * FROM name($1)` | `SELECT * FROM name()`  |
-| PostgreSQL | `SELECT * FROM name(k => $1)`       | `SELECT * FROM name($1)` | `SELECT * FROM name()`  |
+| Dialect    | Named Params                              | Positional                | No Params               |
+| ---------- | ----------------------------------------- | ------------------------- | ----------------------- |
+| MSSQL      | `SELECT * FROM name($1)` (flattened)      | `SELECT * FROM name($1)` | `SELECT * FROM name()`  |
+| PostgreSQL | `SELECT * FROM name(k => $1)`             | `SELECT * FROM name($1)` | `SELECT * FROM name()`  |
+
+A T-SQL `FROM` clause takes only positional arguments, so on MSSQL a params object is flattened to its values in key order. Declare MSSQL TVF params as an array when the order matters to you rather than relying on object key order.
 
 ```typescript
 // Named params — return type inferred from tuple
@@ -449,7 +496,8 @@ const custom = await ctx.tvf<'get_team_members', CustomMember>('get_team_members
 | `config`   | `Config`         | The resolved config object              |
 | `settings` | `Settings`       | Project settings (paths, rules, stages) |
 | `identity` | `Identity`       | Current operator identity               |
-| `observer` | `ObserverEngine` | Event observer for subscriptions        |
+
+There is no `ctx.noorm.observer`. Events come off the process-global `noormObserver` export instead. See [Event Subscriptions](#event-subscriptions).
 
 
 ### ctx.noorm.run — Run Operations
@@ -464,8 +512,12 @@ const result = await ctx.noorm.run.build({ force: true });
 console.log(`Ran ${result.filesRun} files`);
 ```
 
+**Options (`BuildOptions`):** `{ force?: boolean; dryRun?: boolean }`.
+
 **Returns:** `Promise<BatchResult>`. See [Result shape](#run-result-shape) for the `error` and `skipReason` fields you'll find on each entry of `result.files`.
 
+`build()` is the one run method that applies `settings.build.include` / `exclude` and `settings.rules`, so headless callers see the same file set the TUI's Run Build screen shows. Include or exclude entries that matched no file come back as `result.unmatchedInclude` / `result.unmatchedExclude` rather than as a failure: a build over zero files still succeeds, so these arrays are how a mistyped pattern surfaces.
+
 
 #### run.file(filepath, options?)
 
@@ -515,6 +567,8 @@ await ctx.noorm.run.dir('seeds/');
 | `error` | `string` | Only when `status === 'failed'` |
 | `skipReason` | `'unchanged' \| 'already-run'` | Only when `status === 'skipped'` |
 | `durationMs` | `number` | Set for executed and failed files |
+| `renderedSql` | `string` | Only in preview mode (`run.preview`) |
+| `outputPath` | `string` | Only on a dry run that wrote rendered SQL to disk |
 
 Example handling a failed build:
 
@@ -558,36 +612,71 @@ Render SQL files (including templates) without executing. Useful for reviewing w
 ```typescript
 const results = await ctx.noorm.run.preview(['sql/001.sql', 'sql/002.sql']);
 for (const r of results) {
-    console.log(`${r.filepath}:\n${r.sql}`);
+    console.log(`${r.filepath}:\n${r.renderedSql}`);
 }
 ```
 
-**Returns:** `Promise<FileResult[]>` — rendered SQL for each file.
+**Returns:** `Promise<FileResult[]>` — the rendered SQL for each file lands in `renderedSql`, not `sql`. A file that failed to load or render comes back with `status: 'failed'` and an `error` message instead of throwing.
+
+Pass a second argument to write the combined output to a file: `run.preview(paths, 'tmp/preview.sql')`. Rendering resolves every secret into the returned string, so treat preview output as plaintext secrets.
 
 
 ### ctx.noorm.db — Database Operations
 
 
-#### db.truncate()
+#### db.truncate(options?)
 
 Wipe all data, keeping the schema intact.
 
 ```typescript
 const result = await ctx.noorm.db.truncate();
 console.log(`Truncated ${result.truncated.length} tables`);
+
+// Keep a reference table standing.
+await ctx.noorm.db.truncate({ preserve: ['countries'] });
+
+// Or restrict the wipe to a few tables.
+await ctx.noorm.db.truncate({ only: ['users', 'posts'] });
 ```
 
+**Options (`TruncateOptions`):**
+
+| Option            | Type       | Default | Description                                                                |
+| ----------------- | ---------- | ------- | -------------------------------------------------------------------------- |
+| `preserve`        | `string[]` | —       | Tables to leave alone. Falls back to `settings.teardown.preserveTables`.   |
+| `only`            | `string[]` | —       | Truncate only these tables. Inverse of `preserve`.                          |
+| `restartIdentity` | `boolean`  | `true`  | Restart identity / auto-increment sequences.                                |
+| `dryRun`          | `boolean`  | `false` | Return the SQL in `result.statements` without executing it.                 |
+
+**Returns:** `Promise<TruncateResult>` — `{ truncated, preserved, statements, durationMs }`.
+
+A `dryRun` is checked against the config's role but never against a confirmation gate, so a role that may truncate can always look first. A role that may not truncate cannot preview either.
+
 **Implementation notes.** FK constraints are disabled first, every targeted table is `DELETE`d (or `TRUNCATE`d, where the dialect supports it), then constraints are re-enabled. PG/MySQL/SQLite flip a session- or connection-level switch once. MSSQL, which has no session-level toggle, emits one `ALTER TABLE [name] NOCHECK CONSTRAINT ALL` per truncated table on a single connection — replacing the older `sp_MSforeachtable` call that spawned parallel workers and could deadlock. See [dev/teardown.md](../dev/teardown.md#mssql-truncate-strategy) for the full reasoning.
 
 
-#### db.teardown()
+#### db.teardown(options?)
 
-Drop all database objects except noorm tracking tables.
+Drop all database objects except noorm's own internal tables, which cover change tracking, locks, vault, and identities.
 
 ```typescript
 const result = await ctx.noorm.db.teardown();
+
+// Compute the drop plan without executing it.
+const plan = await ctx.noorm.db.teardown({ dryRun: true });
+
+// Leave an application-owned schema untouched.
+await ctx.noorm.db.teardown({ preserveSchemas: ['app_private'] });
 ```
 
+**Options (`TeardownOptions`):** the SDK reads two fields off what you pass, `dryRun` and `preserveSchemas`. It fills `preserveTables` and `postScript` from `settings.teardown` in `settings.yml`. The remaining `TeardownOptions` fields (`keepViews`, `keepFunctions`, `keepProcedures`, `keepTypes`, and a caller-supplied `preserveTables`) are dropped on the way through and have no effect from the SDK.
+
+`preserveSchemas` exists because `preserveTables` is a flat name list: excluding `app_private.secrets` by name would also spare `public.secrets`.
+
+**Returns:** `Promise<TeardownResult>` — `{ dropped: { tables, views, functions, procedures, types, foreignKeys }, preserved, statements, durationMs }`, plus `postScriptResult`, `staleCount`, and `resetRecordId` when they apply.
+
+As with `truncate`, a `dryRun` is gated on the role but not on confirmation.
+
 
 #### db.previewTeardown()
 
@@ -595,12 +684,12 @@ Preview what teardown would drop without executing. Useful for confirming destru
 
 ```typescript
 const preview = await ctx.noorm.db.previewTeardown();
-for (const obj of preview.objects) {
-    console.log(`Would drop ${obj.type}: ${obj.name}`);
+for (const [kind, names] of Object.entries(preview.toDrop)) {
+    console.log(`Would drop ${names.length} ${kind}`);
 }
 ```
 
-**Returns:** `Promise<TeardownPreview>` — list of objects that would be dropped.
+**Returns:** `Promise<TeardownPreview>` — `{ toDrop, toPreserve, statements }`. `toDrop` groups names by object kind (`tables`, `views`, `functions`, `procedures`, `types`, `foreignKeys`); there is no flat `objects` array.
 
 
 #### db.reset()
@@ -611,6 +700,8 @@ Full rebuild: teardown + build.
 await ctx.noorm.db.reset();
 ```
 
+**Returns:** `Promise<void>`. Unlike `teardown()` and `truncate()`, `reset()` takes no options and deliberately ignores `settings.teardown.preserveTables`: it rebuilds the whole schema from `sql/`, so any preserved table would collide with the build's `CREATE TABLE` and abort the rebuild.
+
 **Implementation notes.** Objects are dropped in `FK → Procedures → Functions → Views → Tables → Types` order. Procs/funcs/views go before tables because MSSQL schema-bound objects (`WITH SCHEMABINDING`) hold dependency locks on the tables they reference — dropping the table first fails with `Cannot DROP TABLE ... because it is being referenced by object ...`. Types drop last because TVPs may still be referenced by procs/funcs earlier in the chain. See [dev/teardown.md](../dev/teardown.md#drop-order) for the full reasoning.
 
 
@@ -732,12 +823,12 @@ ctx.noorm.changes.validate(change);
 
 #### changes.apply(name, options?)
 
-Apply a specific change. Pass `{ dryRun: true }` to render rendered SQL to `tmp/` without touching the database, or `{ preview: true }` to emit rendered SQL without writing. `{ force: true }` bypasses the checksum/already-applied check.
+Apply a specific change. Pass `{ dryRun: true }` to render the change to `tmp/` without touching the database, or `{ preview: true }` to emit rendered SQL without writing. `{ force: true }` bypasses the already-applied check.
 
 ```typescript
 const result = await ctx.noorm.changes.apply('2024-01-15-add-users');
 
-// Dry run — does not touch __noorm_change__ or __noorm_executions__.
+// Dry run — does not touch the change tracking tables.
 const dry = await ctx.noorm.changes.apply(
     '2024-01-15-add-users',
     { dryRun: true },
@@ -746,6 +837,8 @@ const dry = await ctx.noorm.changes.apply(
 
 **Options:** `ChangeOptions` — `{ force?: boolean; dryRun?: boolean; preview?: boolean; output?: string | null }`.
 
+**Returns:** `Promise<ChangeResult>`.
+
 
 #### changes.revert(name, options?)
 
@@ -764,7 +857,7 @@ const dry = await ctx.noorm.changes.revert(
 
 #### changes.ff(options?)
 
-Apply all pending changes. Accepts `BatchChangeOptions` — the same fields as `ChangeOptions` plus `abortOnError`. Pass `{ dryRun: true }` to render every pending change to `tmp/` without writing to the database; the tracking tables (`__noorm_change__`, `__noorm_executions__`) are left untouched.
+Apply all pending changes. Accepts `BatchChangeOptions` — the same fields as `ChangeOptions` plus `abortOnError`. Pass `{ dryRun: true }` to render every pending change to `tmp/` without writing to the database; the change tracking tables are left untouched.
 
 ```typescript
 const result = await ctx.noorm.changes.ff();
@@ -788,6 +881,24 @@ const dry = await ctx.noorm.changes.next(2, { dryRun: true });
 ```
 
 
+#### changes.rewind(target, options?)
+
+Revert applied changes in reverse order. Pass a change name to revert back to and including that change, or a number to revert that many of the most recent ones. Accepts the same `BatchChangeOptions` as `ff()`.
+
+```typescript
+// Back out everything applied after (and including) this change.
+const result = await ctx.noorm.changes.rewind('2024-01-15-add-users');
+
+// Or back out the last three.
+const three = await ctx.noorm.changes.rewind(3);
+
+// Render the revert files without touching the database.
+const dry = await ctx.noorm.changes.rewind(3, { dryRun: true });
+```
+
+**Returns:** `Promise<BatchChangeResult>`. A name matching no applied change comes back as a failed batch carrying `result.error` (`No applied change named "..." to rewind to`), not a throw.
+
+
 #### changes.status()
 
 Get status of all changes.
@@ -847,6 +958,26 @@ const overview = await ctx.noorm.db.overview();
 console.log(`Tables: ${overview.tables}, Views: ${overview.views}`);
 ```
 
+**Returns:** `Promise<ExploreOverview>` — counts for `tables`, `views`, `procedures`, `functions`, `types`, `indexes`, `foreignKeys`, `triggers`, `locks`, and `connections`.
+
+
+#### Other explore methods
+
+Tables are not the only object kind. Every `list*` method returns a summary array, and every `describe*` method takes `(name, schema?)` and returns the detail object or `null` when the object does not exist.
+
+| Method                             | Returns                       |
+| ---------------------------------- | ----------------------------- |
+| `db.listViews()`                   | `ViewSummary[]`               |
+| `db.describeView(name, schema?)`   | `ViewDetail \| null`          |
+| `db.listProcedures()`              | `ProcedureSummary[]`          |
+| `db.describeProcedure(name, schema?)` | `ProcedureDetail \| null`  |
+| `db.listFunctions()`               | `FunctionSummary[]`           |
+| `db.describeFunction(name, schema?)` | `FunctionDetail \| null`    |
+| `db.listTypes()`                   | `TypeSummary[]`               |
+| `db.describeType(name, schema?)`   | `TypeDetail \| null`          |
+| `db.listIndexes()`                 | `IndexSummary[]`              |
+| `db.listForeignKeys()`             | `ForeignKeySummary[]`         |
+
 
 ### ctx.noorm.lock — Lock Management
 
@@ -898,13 +1029,15 @@ await ctx.noorm.lock.withLock(async () => {
 Force release any database lock regardless of ownership. Use when a lock is stuck due to a crashed process or stale session.
 
 ```typescript
-const released = await ctx.noorm.lock.forceRelease();
+const { released, holder } = await ctx.noorm.lock.forceRelease();
 if (released) {
-    console.log('Stale lock cleared');
+    console.log(`Stale lock cleared (was held by ${holder})`);
 }
 ```
 
-**Returns:** `Promise<boolean>` — `true` if a lock was released, `false` if none existed.
+**Returns:** `Promise<ForceReleaseResult>` — `{ released: boolean; holder: string | null }`. `holder` is `null` when there was nothing to release. The result object is always truthy, so branch on `released`, not on the return value.
+
+This is the one lock method behind the access policy. Breaking someone else's lock interrupts their in-flight migration, so `viewer` is denied outright and `operator`/`admin` need `yes: true` on the context. Denial throws `ProtectedConfigError`.
 
 
 ### ctx.noorm.templates — Template Operations
@@ -959,6 +1092,10 @@ await dest.disconnect();
 | `exportPath`         | `string`           | —        | Export to .dt file instead of DB insert.     |
 | `passphrase`         | `string`           | —        | Passphrase for .dtzx export encryption.      |
 
+**Returns:** `Promise<TransferResult>` — `{ status, tables, totalRows, durationMs, fkChecksRestored }`. Check `fkChecksRestored`: it is the only signal that referential integrity may still be off, because `status` does not flip when the FK re-enable fails.
+
+The policy gate runs against the **destination** config, not the source, since the destination is the write target. `transfer.plan()` is gated separately on `transfer:plan`, which `operator` and `admin` both hold outright, so planning stays available to a role that may not execute the transfer.
+
 
 #### transfer.plan(destConfig, options?)
 
@@ -1019,6 +1156,8 @@ console.log(`Imported ${result.rowsImported} rows, skipped ${result.rowsSkipped}
 | `onConflict` | `ConflictStrategy` | `'fail'` | Conflict strategy.                   |
 | `truncate`   | `boolean`          | `false`  | Truncate target table before import. |
 
+`importFile` writes to the database, so it is gated on `db:reset`, which requires confirmation for `operator`. `exportTable` only reads and is not gated.
+
 
 ### ctx.noorm.changes — History
 
@@ -1034,18 +1173,72 @@ for (const record of history) {
 }
 ```
 
+**Returns:** `Promise<ChangeHistoryRecord[]>` — one record per operation, each with `id`, `name`, `direction`, `status`, `executedAt`, `executedBy`, `durationMs`, `errorMessage`, and `checksum`.
+
+
+#### changes.historyForChange(name, limit?)
+
+Get execution history for one change, most recent first.
+
+```typescript
+const records = await ctx.noorm.changes.historyForChange('2024-01-15-add-users');
+```
+
+**Returns:** `Promise<ChangeHistoryRecord[]>`.
+
+
+#### changes.getFileHistory(operationId)
+
+Drill into the per-file records behind a single operation. Pass the `id` from a `ChangeHistoryRecord`.
+
+```typescript
+const records = await ctx.noorm.changes.historyForChange('2024-01-15-add-users');
+const files = await ctx.noorm.changes.getFileHistory(records[0].id);
+
+for (const file of files) {
+    console.log(`${file.filepath}: ${file.status}`);
+}
+```
+
+**Returns:** `Promise<FileHistoryRecord[]>` — `id`, `changeId`, `filepath`, `fileType`, `checksum`, `status`, `skipReason`, and the error message when the file failed.
+
 
 ### ctx.noorm.secrets — Secrets
 
 
 #### secrets.get(key)
 
-Get a config-scoped secret.
+Get a config-scoped secret. Synchronous, and needs no connection: these live in local encrypted state, not the database.
 
 ```typescript
 const apiKey = ctx.noorm.secrets.get('API_KEY');
 ```
 
+**Returns:** `string | undefined` — not a promise, and `undefined` rather than `null` when the key is unset.
+
+
+#### secrets.list()
+
+List the config's secret key names. Values are never returned, so a caller that only needs to know which secrets exist never handles them.
+
+```typescript
+const keys = ctx.noorm.secrets.list();
+```
+
+**Returns:** `string[]` — synchronous.
+
+
+#### secrets.set(key, value) / secrets.delete(key)
+
+Write and remove config-scoped secrets. Both are async and both need `secret:write`, which is `confirm` for `operator`.
+
+```typescript
+await ctx.noorm.secrets.set('API_KEY', 'sk-live-...');
+await ctx.noorm.secrets.delete('OLD_KEY');
+```
+
+**Returns:** `Promise<void>` for both.
+
 
 ### ctx.noorm.vault — Vault (Encrypted Team Secrets)
 
@@ -1094,7 +1287,7 @@ Set a vault secret. Requires the caller's private key for vault key decryption.
 await ctx.noorm.vault.set('API_KEY', 'sk-live-...', privateKey);
 ```
 
-**Returns:** `Promise<void>` — throws on failure.
+**Returns:** `Promise<void>`. Throws `VaultAccessError` when the private key yields no usable vault key: either the vault was never propagated to this identity, or the key does not match. The two causes are deliberately indistinguishable.
 
 
 #### vault.get(key, privateKey)
@@ -1119,7 +1312,7 @@ for (const [key, secret] of Object.entries(all)) {
 }
 ```
 
-**Returns:** `Promise<Record<string, VaultSecret>>`
+**Returns:** `Promise<Record<string, VaultSecret>>` — an empty object when the caller has no vault access, mirroring `get()` returning `null`. Neither read throws on missing access.
 
 
 #### vault.list()
@@ -1168,23 +1361,30 @@ const result = await ctx.noorm.vault.propagate(privateKey);
 console.log(`Propagated to ${result.propagatedTo.length} new users`);
 ```
 
-**Returns:** `Promise<VaultPropagationResult>`
+**Returns:** `Promise<VaultPropagationResult>` — `{ propagatedTo, alreadyHadAccess, failed }`. A non-empty `failed` means the operation partially succeeded: a teammate believes they have access and does not. Treat it as an error, not a warning.
 
 
 #### vault.copy(destConfig, keys, privateKey, options?)
 
 Copy vault secrets to another config's database. Useful for seeding a new environment with secrets from an existing one. Throws on failure.
 
+`keys` takes either an explicit list or the literal `'all'`.
+
 ```typescript
 const result = await ctx.noorm.vault.copy(
     destConfig,
     ['API_KEY', 'DB_TOKEN'],
     privateKey,
 );
-console.log(`Copied ${result.copied} secrets`);
+console.log(`Copied ${result.copied.length} secrets`);
+
+// Or copy everything.
+await ctx.noorm.vault.copy(destConfig, 'all', privateKey);
 ```
 
-**Returns:** `Promise<VaultCopyResult>` — throws on failure.
+**Options (`VaultCopyOptions`):** `force` (overwrite existing destination secrets, default `false`) and `dryRun` (run the full preflight and report what would happen without writing).
+
+**Returns:** `Promise<VaultCopyResult>` — `{ copied: string[]; skipped: string[]; errors: Array<{ key, error }> }`. All three are key lists, not counts. `skipped` holds keys that already exist on the destination and were not forced. This is the one vault method that checks the access policy on both the source and the destination config.
 
 
 ### ctx.noorm.utils — Utilities
@@ -1227,6 +1427,8 @@ noormObserver.on('change:complete', (event) => {
 });
 ```
 
+`noormObserver` is a process-global singleton, not a per-context bus. A process that calls `createContext()` more than once (a server juggling several tenant databases, say) sees every context's events on this one stream. Config-scoped events carry `configName` so you can filter, but not every event does: `file:after` and `change:complete` do not, while `file:before`, `run:file`, `lock:*`, `secret:*`, and `db:*` do. Check the payload type before relying on it.
+
 
 ## Environment Variables
 
@@ -1275,9 +1477,17 @@ skip `attempt` and let it propagate. Never wrap an SDK call in try-catch.
 
 Carve-outs that don't follow that plain throw-and-`attempt` pattern:
 `ctx.noorm.utils.testConnection()` returns `{ ok, error? }` by design — a probe reporting failure as
-data, not an exception. `ctx.transaction(...)` callbacks must throw to trigger Kysely's rollback —
-throwing is the rollback signal, so don't swallow it inside the callback. Raw `ctx.kysely` queries
-throw whatever the driver throws.
+data, not an exception. `ctx.noorm.vault.get()` and `.getAll()` return `null` and `{}` on missing
+vault access rather than throwing, and `ctx.noorm.vault.init()` returns `null` when the vault already
+exists. `ctx.noorm.run.*` and `ctx.noorm.changes.ff/next/rewind` report per-item failures on the
+result (`result.files[].error`, `result.error`) instead of throwing, so a non-throwing call is not
+proof of success; check `status`. `ctx.transaction(...)` callbacks must throw to trigger Kysely's
+rollback — throwing is the rollback signal, so don't swallow it inside the callback. Raw `ctx.kysely`
+queries throw whatever the driver throws.
+
+One gap in the "named errors" rule: a policy denial caught at the SDK seam throws `ProtectedConfigError`,
+but a denial caught deeper, inside the runner or the transfer module, throws a plain `Error` carrying the
+same message. Match on `ProtectedConfigError` where you can, and fall back to the message otherwise.
 
 ```typescript
 import { attempt } from '@logosdx/utils';
@@ -1286,6 +1496,9 @@ import {
     tvp,
     RequireTestError,
     ProtectedConfigError,
+    NotConnectedError,
+    VaultAccessError,
+    ImpersonationError,
     LockAcquireError,
 } from '@noormdev/sdk';
 
@@ -1306,6 +1519,19 @@ if (lockErr instanceof LockAcquireError) {
 }
 ```
 
+The full set of `instanceof`-matchable errors exported from `@noormdev/sdk`:
+
+| Error | Thrown when |
+| --- | --- |
+| `RequireTestError` | `requireTest: true` and the config lacks `isTest: true`. Carries `configName`. |
+| `NotConnectedError` | A namespace method needing a live connection ran before `connect()` or after `disconnect()`. |
+| `ProtectedConfigError` | The config's access policy denied the operation, or requires a confirmation `yes: true` did not supply. Carries `configName` and `operation`. |
+| `VaultAccessError` | `vault.set()` got a private key that yields no usable vault key. Carries `configName`. |
+| `ImpersonationError` | `impersonate()` on MySQL or SQLite, or with an invalid username. |
+| `LockAcquireError` | The lock is held by someone else. Carries `holder`, `heldSince`, `expiresAt`, `configName`, `reason`. |
+| `LockExpiredError` | The lock expired mid-operation. Carries `configName`, `identity`, `expiredAt`. |
+| `ChangeValidationError`, `ChangeNotFoundError`, `ChangeAlreadyAppliedError`, `ChangeNotAppliedError`, `ChangeOrphanedError`, `ManifestReferenceError` | Change parsing and execution problems. |
+
 
 ## TypeScript Support
 
@@ -1377,6 +1603,7 @@ import type {
     ExploreOverview,
 
     // Operations
+    TruncateOptions,
     TruncateResult,
     TeardownResult,
     TeardownPreview,
@@ -1411,8 +1638,20 @@ import type {
     // TVP
     TvpValue,
 
+    // Impersonation
+    ImpersonatedScope,
+
+    // Proc/func/tvf tuple helpers
+    ExtractArgs,
+    ExtractReturn,
+
     // Events
     NoormEvents,
     NoormEventNames,
 } from '@noormdev/sdk';
 ```
+
+Four shapes named by public method signatures are not re-exported from the package: `BatchChangeOptions`
+(`changes.ff` / `next` / `rewind`), `TeardownOptions` (`db.teardown`), `ForceReleaseResult`
+(`lock.forceRelease`'s return), and `ConnectionRetryOptions` (`connect`'s parameter). Declare those
+inline until they are exported.
diff --git a/docs/tui.md b/docs/tui.md
index 19dcb02f..ceec51a4 100644
--- a/docs/tui.md
+++ b/docs/tui.md
@@ -25,25 +25,30 @@ The TUI is a dedicated subcommand — every other `noorm` command runs as a non-
                               ┌─────────┐
                               │  Home   │
                               └────┬────┘
-        ┌──────────┬──────────┬────┴────┬──────────┬──────────┐
-        │          │          │         │          │          │
-     [c]│       [g]│       [r]│      [d]│       [s]│       [k]│
-        ▼          ▼          ▼         ▼          ▼          ▼
-   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
-   │ Config │ │ Change │ │  Run   │ │Database│ │Settings│ │Secrets │
-   │  List  │ │  List  │ │  Menu  │ │  Menu  │ │  Menu  │ │  List  │
-   └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘
+        ┌──────────┬──────────┬────┴────┬──────────┐
+        │          │          │         │          │
+     [c]│       [g]│       [r]│      [d]│       [s]│
+        ▼          ▼          ▼         ▼          ▼
+   ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+   │ Config │ │ Change │ │  Run   │ │Database│ │Settings│
+   │  List  │ │  List  │ │  Menu  │ │  Menu  │ │  Menu  │
+   └────────┘ └────────┘ └────────┘ └────────┘ └────────┘
         │          │          │         │
         │          │          │         ├── Explore (tables, views...)
         │          │          │         └── Terminal (SQL REPL)
         │          │          │
-        │          │          └── Build, File, Directory
+        │          │          └── Build, File, Directory, Exec, Inspect
         │          │
-        │          └── FF, Run, Revert, History
+        │          └── FF, Next, Run, Revert, Rewind, History
         │
-        └── Add, Edit, Delete, Use, Validate, Export, Import
+        ├── Add, Edit, Delete, Copy, Use
+        │
+        └──[k]── Secrets List
 ```
 
+Secrets hang off a config, so `k` opens them from the Config List, not from
+Home. Export, import, and validate sit behind `[+] More` on the Config List.
+
 
 ## Keyboard Shortcuts
 
@@ -267,12 +272,15 @@ See [Locking](/dev/lock).
 
 ### Quick Config Switching
 
-From home, press `c` then the number of the config you want, then `Enter` to activate:
+From home, press `c`, arrow to the config you want, then `Enter` to activate it.
+The config list is not numbered, so the digits do nothing there:
 
 ```
-c → 2 → Enter
+c → ↓ → Enter
 ```
 
+`Enter` on the config that is *already* active opens its edit form instead.
+
 
 ### Fast Forward All Changes
 
@@ -290,8 +298,10 @@ r → b
 
 ### Check Connection
 
+Validate lives behind `[+] More` on the config list:
+
 ```
-c → v (validate current config)
+c → + → v (validate highlighted config)
 ```
 
 
diff --git a/docs/why-noorm.md b/docs/why-noorm.md
new file mode 100644
index 00000000..36482ad5
--- /dev/null
+++ b/docs/why-noorm.md
@@ -0,0 +1,109 @@
+---
+title: Why noorm
+description: noorm is the fifth attempt at one problem. Here is the problem, the CLIs that came before, and the questions that kept making the tool bigger.
+---
+
+# Why noorm
+
+
+I stopped using ORMs and needed something to run the SQL.
+
+That is the whole origin. Everything else in noorm arrived as an answer to a question I hit while working without one.
+
+
+## The tools that came first
+
+
+noorm is the fifth attempt. The first three were about the interface, and each one replaced the last because I needed something more robust: **minimist** first, then **cmd-ts**, then **oclif**. The bar kept rising. I wanted a CLI that was discoverable by someone being onboarded, easy to use without a manual, and easy to keep building on.
+
+Then I scrapped all of it and moved to **citty** and **@clack/prompts**, which fit what noorm actually does far better than any of the three.
+
+Around the same time I was experimenting with terminal interfaces and tried **Ink**. Testing it against the CLI settled something. Running commands means remembering commands. A screen that shows you your configs, your pending changes, and your schema while you decide is a better workflow than typing a verb and hoping you got the flags right, because the decision needs data in front of it and a CLI gives you none.
+
+That produced the split noorm still has. Anything interactive lives in the [TUI](/tui): setup wizards, config editing, secrets, browsing the schema. Anything automatable lives in the [CLI](/headless), where it belongs, so the same operations run headless in CI with JSON output.
+
+
+## The questions that kept arriving
+
+
+None of this was designed up front. It was excavated. Each row is a question I could not answer with what I had at the time.
+
+| Question | What it became |
+|---|---|
+| How do I run SQL? | A directory of files, executed in order |
+| How do I undo one? | Forward and revert pairs, tracked per change |
+| How do I test against it? | A real database with safety guards, not mocks |
+| How do I express what DDL makes painful? | Templates that render SQL from YAML |
+| How do I seed data? | Templates again, plus transfer between databases |
+| Where does connection configuration live? | Configs you can export and hand to a teammate |
+| How do I onboard someone onto four environments? | Stages, with required and optional variables |
+| Where do team secrets live? | An encrypted vault table inside the database |
+| What ran, by whom, and why did it break? | History that records the operator and the error |
+| How do I re-run the idempotent objects? | Manifests |
+
+Three of those are worth more than a table row.
+
+
+### Templates are not just per-environment strings
+
+
+Rendering one file differently for dev and production is the obvious use. It was not the reason.
+
+Templates exist so seed data can be expressed and iterated on, and so YAML can become DDL that is miserable to write by hand. SQL Server's scheduled jobs are the clearest case: expressing a schedule semantically and rendering it into the DDL that creates the job beats hand-writing that DDL every time. The same goes for roles and permissions across stored procedures and views. A YAML list of who gets what is readable and diffable. The forty `GRANT` statements it renders into are neither.
+
+So the templating layer is where iteration happens, and SQL is the output rather than the source you maintain.
+
+
+### History records why, not just what
+
+
+Every applied change is recorded with its status, when it ran, **who ran it**, and the **error message** if it failed. That last one is the part even ORMs skip.
+
+It matters when a change fails, you fix it, and you run it again. Something that broke during the failed attempt may not surface for days. A history with the actual error lets you trace back to which run went wrong instead of guessing. Recording the operator means a pattern of failures has a name attached to it.
+
+The reason for a change almost never gets written down anywhere. That is what `changelog.md` in the change folder is for: the justification, next to the SQL it justifies.
+
+**Manifests** handle the objects that are meant to be re-run. Views, functions, stored procedures, and the templates that generate crons or permissions are all idempotent, so a manifest lists them and the change re-runs them. The point is that fixing a stored procedure stops being something that happens in a SQL editor at 11pm and starts being a tracked change like any other.
+
+
+### Configuration is something you hand to someone
+
+
+A config is exportable. Sharing one goes through the TUI, where export encrypts to the recipient's public key with X25519 key exchange and AES-256-GCM, and leaves credentials out, so the recipient supplies their own username and password on import. You can export local dev, local test, staging, and production, send all four, and the other person fills in only the parts that are theirs. (The CLI's `config export` is a different tool: plain JSON, credentials included, for your own backups.)
+
+**Stages** make that prescriptive. Rather than describing your environments in a README, you define them once, and everyone gets the same shape with the details left blank. A stage declares its variables as required or optional, and a build fails with a clear error when a required one is missing instead of rendering something half-formed. Configs are typed `local` or `remote`, which is the distinction that decides how careful the tool should be. Losing a local dev database costs nothing. Production is a different question, which is what [access roles](/guide/environments/configs#access-roles) gate.
+
+**The vault** covers what stages cannot: secrets the whole team needs. Those live encrypted in the database itself, in `noorm.vault` where the dialect has schemas and a `__noorm_vault__` table where it does not, so they distribute automatically rather than over Slack. They sit lowest in the precedence chain, so a local override always wins.
+
+
+## The Arrival of LLMs
+
+
+The constraint changed. Writing SQL stopped being the slow part, so the slow part became reviewing SQL that an agent wrote quickly and confidently and sometimes wrongly.
+
+That pushed the tool in three directions at once.
+
+**Safeguards**, so a confident mistake cannot reach production: per-channel [access roles](/guide/environments/configs#access-roles), dry runs, checksums, and a typed confirmation on anything destructive.
+
+**Guidance**, so an agent writes code that matches the conventions here instead of guessing at them. That is what the [agent skill](/getting-started/installation) is for.
+
+**Planning**, because the cheapest moment to catch a bad schema is before it exists.
+
+That last one turned into a separate tool. See [Information modeling](/modeling/).
+
+
+## Where to start
+
+
+<div class="next-steps">
+
+[**Installation**](/getting-started/installation)
+Get noorm installed and running.
+
+[**Concepts**](/getting-started/concepts)
+How SQL files and changes divide the work.
+
+[**Information modeling**](/modeling/)
+Design the data model before you write the schema.
+
+</div>
diff --git a/package.json b/package.json
index 635688e6..1db6be5b 100644
--- a/package.json
+++ b/package.json
@@ -39,7 +39,7 @@
         "terminal"
     ],
     "author": "",
-    "license": "MIT",
+    "license": "Apache-2.0",
     "engines": {
         "node": ">=22.13",
         "bun": ">=1.2"
diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
index ee92eec1..d6456956 100644
--- a/packages/cli/LICENSE
+++ b/packages/cli/LICENSE
@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 Danilo Alonso
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/cli/NOTICE b/packages/cli/NOTICE
new file mode 100644
index 00000000..49f33835
--- /dev/null
+++ b/packages/cli/NOTICE
@@ -0,0 +1,2 @@
+@noormdev/cli
+Copyright 2026 Danilo Alonso
diff --git a/packages/cli/package.json b/packages/cli/package.json
index dc8b0e22..055e9aef 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -8,7 +8,8 @@
   },
   "files": [
     "noorm.js",
-    "scripts"
+    "scripts",
+    "NOTICE"
   ],
   "scripts": {
     "postinstall": "node scripts/postinstall.js"
@@ -23,7 +24,7 @@
     "cli",
     "noorm"
   ],
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/noormdev/noorm.git"
diff --git a/packages/sdk/LICENSE b/packages/sdk/LICENSE
index ee92eec1..d6456956 100644
--- a/packages/sdk/LICENSE
+++ b/packages/sdk/LICENSE
@@ -1,21 +1,202 @@
-MIT License
-
-Copyright (c) 2026 Danilo Alonso
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/packages/sdk/NOTICE b/packages/sdk/NOTICE
new file mode 100644
index 00000000..4209ebe6
--- /dev/null
+++ b/packages/sdk/NOTICE
@@ -0,0 +1,2 @@
+@noormdev/sdk
+Copyright 2026 Danilo Alonso
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
index e3f42eca..2e525b7b 100644
--- a/packages/sdk/package.json
+++ b/packages/sdk/package.json
@@ -14,7 +14,8 @@
   },
   "files": [
     "dist",
-    "!dist/**/*.map"
+    "!dist/**/*.map",
+    "NOTICE"
   ],
   "sideEffects": false,
   "peerDependencies": {
@@ -53,7 +54,7 @@
     "kysely",
     "noorm"
   ],
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/noormdev/noorm.git"
diff --git a/scripts/check-flag-placement.sh b/scripts/check-flag-placement.sh
index cdf23ae6..6d9f20d1 100755
--- a/scripts/check-flag-placement.sh
+++ b/scripts/check-flag-placement.sh
@@ -32,6 +32,8 @@ TARGETS=(README.md docs skills examples)
 # the correct form under a "does not work"/overload-explainer heading:
 # - docs/guide/troubleshooting.md: the flag-placement entry contrasts broken vs. working forms
 # - docs/cli/flags.md: the placement explainer and `--config`/`-c` overload section contrast the two forms
+# - docs/dev/headless.md: the CLI-architecture page documents extractGlobalCwd by
+#   showing the rejected form next to the error it produces, under a "Rejected:" comment
 # - docs/design/v1-49-54-cli-field-defects.md: this checkpoint's own design doc, which
 #   narrates the "form that cannot work" as the defect under investigation
 # - examples/llm-memory-db-pg/{REPORT.md,REPORT-PHASE-1.md,postgres-problems.md}: dated
@@ -39,7 +41,7 @@ TARGETS=(README.md docs skills examples)
 #   already stating the "must come after the subcommand" rule as a quirk they hit
 # - examples/llm-memory-db-mssql/mssql-problems.md: same — a dated repro transcript, not
 #   instructional prose, predating this branch
-EXEMPT_REGEX='^(docs/guide/troubleshooting\.md|docs/cli/flags\.md|docs/design/v1-49-54-cli-field-defects\.md|examples/llm-memory-db-pg/(REPORT\.md|REPORT-PHASE-1\.md|postgres-problems\.md)|examples/llm-memory-db-mssql/mssql-problems\.md):'
+EXEMPT_REGEX='^(docs/guide/troubleshooting\.md|docs/cli/flags\.md|docs/dev/headless\.md|docs/design/v1-49-54-cli-field-defects\.md|examples/llm-memory-db-pg/(REPORT\.md|REPORT-PHASE-1\.md|postgres-problems\.md)|examples/llm-memory-db-mssql/mssql-problems\.md):'
 
 FAILED=0
 
diff --git a/src/cli/ci/init.ts b/src/cli/ci/init.ts
index a230446c..f82e1fc5 100644
--- a/src/cli/ci/init.ts
+++ b/src/cli/ci/init.ts
@@ -59,6 +59,11 @@ const initCommand = defineCommand({
             description: 'Overwrite existing state.enc (backs it up first)',
             default: false,
         },
+        test: {
+            type: 'boolean',
+            description: 'Mark the config as a test database (satisfies the SDK\'s requireTest guard)',
+            default: false,
+        },
         yes: sharedArgs.yes,
         json: sharedArgs.json,
     },
@@ -206,10 +211,16 @@ const initCommand = defineCommand({
         // Validated rather than hand-built and trusted: this is the one path
         // that writes a config nobody reviewed, and it used to persist shapes
         // the schema forbids for every later consumer to trip over.
+        // Opt-in, not automatic. `isTest` is what the SDK's `requireTest`
+        // guard checks before letting a suite truncate or teardown, so
+        // stamping it on every config this command creates made the guard
+        // pass against a production database bootstrapped by the documented
+        // prod-CI flow. Env-only resolution already defaults it to false
+        // (`core/config/resolver.ts`); this now agrees with it.
         const [config, parseErr] = attemptSync(() => parseConfig({
             name: configName,
             type: 'remote',
-            isTest: true,
+            isTest: args.test,
             access: DEFAULT_ACCESS,
             connection,
         }) as Config);
@@ -255,7 +266,7 @@ const initCommand = defineCommand({
                     name: configName,
                     dialect,
                     database: connection.database,
-                    isTest: true,
+                    isTest: args.test,
                 },
                 stateFile,
                 ...(backedUpTo ? { backedUpTo } : {}),
@@ -264,7 +275,7 @@ const initCommand = defineCommand({
                 'CI runtime initialized.',
                 `  Identity:      ${envIdentity.identity.name} <${envIdentity.identity.email}>`,
                 `  Fingerprint:   ${envIdentity.identity.identityHash}`,
-                `  Config:        ${configName} (${dialect}, isTest=true)`,
+                `  Config:        ${configName} (${dialect}, isTest=${args.test})`,
                 `  Database:      ${connection.database}`,
                 `  State file:    ${stateFile}`,
                 ...(backedUpTo ? [`  Previous state backed up to: ${backedUpTo}`] : []),
diff --git a/src/cli/config/validate.ts b/src/cli/config/validate.ts
index d2e45b9d..063a3add 100644
--- a/src/cli/config/validate.ts
+++ b/src/cli/config/validate.ts
@@ -62,7 +62,11 @@ const validateCommand = defineCommand({
 
         const text = `${args.name}: ${statusText}\n${lines.join('\n')}`;
 
-        outputResult(args, { config: args.name, valid, checks }, text);
+        // Explicit `success`: toJsonEnvelope derives it from a `status` field
+        // and defaults to true, so an invalid config would report success:true
+        // while exiting 1, and a CI job branching on .success would read a
+        // failed validation as a pass.
+        outputResult(args, { success: valid, config: args.name, valid, checks }, text);
         process.exit(valid ? 0 : 1);
 
     },
diff --git a/src/cli/db/teardown.ts b/src/cli/db/teardown.ts
index abe2d85b..4fe37db6 100644
--- a/src/cli/db/teardown.ts
+++ b/src/cli/db/teardown.ts
@@ -67,9 +67,15 @@ const teardownCommand = defineCommand({
 
         const postScript = result.postScriptResult;
 
+        // Decided before the payload is written: toJsonEnvelope defaults
+        // `success` to true when the payload carries neither `success` nor
+        // `status`, so the JSON claimed success while the process exited 1.
+        const postScriptFailed = Boolean(postScript && !postScript.executed);
+
         if (args.json) {
 
             outputResult(args, {
+                success: !postScriptFailed,
                 dropped: result.dropped,
                 count: droppedCount,
                 ...(postScript ? { postScriptResult: postScript } : {}),
@@ -81,11 +87,11 @@ const teardownCommand = defineCommand({
         // The objects are already gone, so this is not a rollback — but a
         // teardown whose post-script never ran is half-finished, and exiting
         // 0 told every pipeline it was complete.
-        if (postScript && !postScript.executed) {
+        if (postScriptFailed) {
 
             if (!args.json) {
 
-                outputError(args, `Post-teardown script failed: ${postScript.error ?? 'Unknown error'}`);
+                outputError(args, `Post-teardown script failed: ${postScript?.error ?? 'Unknown error'}`);
 
             }
 
diff --git a/src/cli/sql/repl.ts b/src/cli/sql/repl.ts
index 523f0517..d0d2f5d8 100644
--- a/src/cli/sql/repl.ts
+++ b/src/cli/sql/repl.ts
@@ -48,7 +48,7 @@ const replCommand = defineCommand({
             process.stderr.write(
                 'Error: noorm sql repl is interactive only. For non-interactive SQL, use:\n' +
                 '  noorm sql query "SELECT 1"            # one-shot\n' +
-                '  noorm sql --file query.sql            # from a file\n',
+                '  noorm sql query --file query.sql      # from a file\n',
             );
             process.exit(EXIT.USAGE);
 
diff --git a/src/core/change/executor.ts b/src/core/change/executor.ts
index 93a2fa73..c2decbc6 100644
--- a/src/core/change/executor.ts
+++ b/src/core/change/executor.ts
@@ -1275,6 +1275,13 @@ function getDryRunOutputPath(projectRoot: string, filepath: string): string {
 
 /**
  * Write rendered SQL to tmp/ directory for dry run.
+ *
+ * Owner-only on both the file and any directory created for it, matching
+ * the runner's `writeDryRunOutput`. The rendered output holds every secret
+ * the template resolved, in plaintext, and `noorm init` does not gitignore
+ * `tmp/`. This path used to write with default permissions, so a change
+ * dry run left secrets group- and world-readable while an identical run
+ * through the runner did not.
  */
 async function writeDryRunOutput(
     projectRoot: string,
@@ -1286,10 +1293,10 @@ async function writeDryRunOutput(
 
     // Ensure directory exists
     const outputDir = path.dirname(outputPath);
-    await mkdir(outputDir, { recursive: true });
+    await mkdir(outputDir, { recursive: true, mode: 0o700 });
 
     // Write file
-    await fsWriteFile(outputPath, content, 'utf-8');
+    await fsWriteFile(outputPath, content, { encoding: 'utf-8', mode: 0o600 });
 
 }
 
diff --git a/src/core/change/history.ts b/src/core/change/history.ts
index 2ecfc497..f9e7df7d 100644
--- a/src/core/change/history.ts
+++ b/src/core/change/history.ts
@@ -14,7 +14,7 @@
  * ```typescript
  * import { ChangeHistory } from './history'
  *
- * const history = new ChangeHistory(db, 'production')
+ * const history = new ChangeHistory(db, 'production', 'postgres')
  *
  * // Check if change needs to run
  * const result = await history.needsRun('2024-01-15-add-users', 'abc123...')
@@ -141,7 +141,7 @@ export function hydrateDate(
  *
  * @example
  * ```typescript
- * const history = new ChangeHistory(db, 'production')
+ * const history = new ChangeHistory(db, 'production', 'postgres')
  *
  * // Create operation record
  * const opId = await history.createOperation({
@@ -170,7 +170,7 @@ export class ChangeHistory {
     readonly #configName: string;
     readonly #dialect: Dialect;
 
-    constructor(db: Kysely<NoormDatabase>, configName: string, dialect: Dialect = 'sqlite') {
+    constructor(db: Kysely<NoormDatabase>, configName: string, dialect: Dialect) {
 
         this.#db = db;
         this.#ndb = noormDb(db, dialect);
diff --git a/src/core/change/tracker.ts b/src/core/change/tracker.ts
index bf31ce80..43a1d21b 100644
--- a/src/core/change/tracker.ts
+++ b/src/core/change/tracker.ts
@@ -12,7 +12,7 @@
  * ```typescript
  * import { ChangeTracker } from './tracker'
  *
- * const tracker = new ChangeTracker(db, 'production')
+ * const tracker = new ChangeTracker(db, 'production', 'postgres')
  *
  * // Check if change can be reverted
  * const result = await tracker.canRevert('2024-01-15-add-users', false)
@@ -81,7 +81,7 @@ export interface CanRevertResult {
  *
  * @example
  * ```typescript
- * const tracker = new ChangeTracker(db, 'dev')
+ * const tracker = new ChangeTracker(db, 'dev', 'postgres')
  *
  * // Use inherited methods from Tracker
  * const opId = await tracker.createOperation({
@@ -104,7 +104,7 @@ export class ChangeTracker extends Tracker {
     readonly #tables: ReturnType<typeof getNoormTables>;
     readonly #configName: string;
 
-    constructor(db: Kysely<NoormDatabase>, configName: string, dialect: Dialect = 'sqlite') {
+    constructor(db: Kysely<NoormDatabase>, configName: string, dialect: Dialect) {
 
         super(db, configName, dialect);
         this.#ndb = noormDb(db, dialect);
diff --git a/src/core/runner/runner.ts b/src/core/runner/runner.ts
index 5c350acc..33b85610 100644
--- a/src/core/runner/runner.ts
+++ b/src/core/runner/runner.ts
@@ -205,6 +205,19 @@ export async function runFile(
         configName: context.configName,
     });
 
+    // Dry run renders to tmp/ and never reaches the database. This has to sit
+    // ahead of the tracker: executeFiles returns before creating an operation,
+    // and runFile must match or a dry run leaves history claiming the file ran.
+    // The policy assertion above still applies — rendering resolves secrets to
+    // disk, so it is gated the same as a real run.
+    if (opts.dryRun) {
+
+        const results = await executeDryRun(context, [filepath]);
+
+        return results[0]!;
+
+    }
+
     // For single file, we still create an operation record for tracking
     const tracker = new Tracker(context.db, context.configName, context.dialect ?? 'postgres');
     const operationName = `run:${new Date().toISOString()}`;
diff --git a/src/core/runner/tracker.ts b/src/core/runner/tracker.ts
index 960ae5d7..8fefa923 100644
--- a/src/core/runner/tracker.ts
+++ b/src/core/runner/tracker.ts
@@ -69,7 +69,7 @@ export class Tracker {
     readonly #configName: string;
     readonly #dialect: Dialect;
 
-    constructor(db: Kysely<NoormDatabase>, configName: string, dialect: Dialect = 'sqlite') {
+    constructor(db: Kysely<NoormDatabase>, configName: string, dialect: Dialect) {
 
         this.#db = db;
         this.#ndb = noormDb(db, dialect);
diff --git a/src/core/transfer/planner.ts b/src/core/transfer/planner.ts
index 2e55334a..80c8206d 100644
--- a/src/core/transfer/planner.ts
+++ b/src/core/transfer/planner.ts
@@ -245,8 +245,16 @@ async function listUserTables(
 
     }
 
-    // Filter to requested tables
-    let filtered = tables.filter((t) => !t.name.startsWith('__noorm_'));
+    // Drop noorm's own tracking tables, both spellings. MySQL and SQLite keep
+    // the `__noorm_` prefix in the default schema; on PostgreSQL and SQL Server
+    // schema migration v2 moved them into a dedicated `noorm` schema under
+    // clean names (`change`, `vault`, `identities`), where the prefix test
+    // matches nothing. Missing the schema let a transfer copy the encrypted
+    // vault and the identity table into the destination. Explore and teardown
+    // already exclude the schema at the dialect layer.
+    let filtered = tables.filter(
+        (t) => !t.name.startsWith('__noorm_') && t.schema !== 'noorm',
+    );
 
     if (options.tables && options.tables.length > 0) {
 
diff --git a/src/sdk/namespaces/transfer.ts b/src/sdk/namespaces/transfer.ts
index 9752ade1..5ce70806 100644
--- a/src/sdk/namespaces/transfer.ts
+++ b/src/sdk/namespaces/transfer.ts
@@ -73,7 +73,13 @@ export class TransferNamespace {
         options?: TransferOptions,
     ): Promise<TransferPlan> {
 
-        const [plan, err] = await getTransferPlan(this.#state.config, destConfig, options);
+        // Same channel injection as to(): getTransferPlan gates on
+        // options.channel ?? 'user', so without this an agent-channel context
+        // has its plan authorised with human permissions.
+        const [plan, err] = await getTransferPlan(this.#state.config, destConfig, {
+            ...options,
+            channel: this.#state.options.channel ?? 'user',
+        });
 
         if (err) throw err;
 
diff --git a/tests/cli/ci/init.test.ts b/tests/cli/ci/init.test.ts
index bde98893..ce809eda 100644
--- a/tests/cli/ci/init.test.ts
+++ b/tests/cli/ci/init.test.ts
@@ -112,13 +112,35 @@ describe('cli: noorm ci init', () => {
         expect(json.success).toBe(true);
         expect(json.config.name).toBe('ci');
         expect(json.config.dialect).toBe('postgres');
-        expect(json.config.isTest).toBe(true);
         expect(json.identity.source).toBe('env');
 
         expect(existsSync(join(tmpDir, '.noorm', 'state', 'state.enc'))).toBe(true);
 
     });
 
+    it('does not mark the config as a test database by default', () => {
+
+        const result = runInit(tmpDir, { ...validIdentityEnv(), ...validConnectionEnv() }, ['--json']);
+
+        expect(result.status).toBe(0);
+
+        // isTest is what the SDK's requireTest guard checks before letting a
+        // suite truncate or teardown. Stamping it on every config this command
+        // creates made that guard pass against a production database
+        // bootstrapped by the documented prod-CI flow.
+        expect(JSON.parse(result.stdout.trim()).config.isTest).toBe(false);
+
+    });
+
+    it('marks the config as a test database when --test is passed', () => {
+
+        const result = runInit(tmpDir, { ...validIdentityEnv(), ...validConnectionEnv() }, ['--json', '--test']);
+
+        expect(result.status).toBe(0);
+        expect(JSON.parse(result.stdout.trim()).config.isTest).toBe(true);
+
+    });
+
     it('uses --name to override the config name', () => {
 
         const result = runInit(
diff --git a/tests/core/change/executor-retry.test.ts b/tests/core/change/executor-retry.test.ts
index e1c9f268..bce52a89 100644
--- a/tests/core/change/executor-retry.test.ts
+++ b/tests/core/change/executor-retry.test.ts
@@ -178,7 +178,7 @@ describe('change: executor retry', () => {
         expect(aExecutions[1]?.status).toBe('skipped');
 
         // Cross-check via ChangeHistory's own query surface
-        const history = new ChangeHistory(db, 'test');
+        const history = new ChangeHistory(db, 'test', 'sqlite');
 
         const op1Files = await history.getFileHistory(result1.operationId!);
         expect(op1Files.find((f) => f.filepath === relA)?.status).toBe('success');
diff --git a/tests/core/change/executor.test.ts b/tests/core/change/executor.test.ts
index 201b46eb..2f7bd7aa 100644
--- a/tests/core/change/executor.test.ts
+++ b/tests/core/change/executor.test.ts
@@ -173,7 +173,7 @@ describe('change: executor', () => {
             expect(result.error).toBeUndefined();
 
             // Verify database record is marked as success
-            const history = new ChangeHistory(db, 'test');
+            const history = new ChangeHistory(db, 'test', 'sqlite');
             const statuses = await history.getAllStatuses();
             const status = statuses.get('test-add-table');
 
@@ -206,7 +206,7 @@ describe('change: executor', () => {
             expect(result.files[1]?.status).toBe('failed');
 
             // Verify database records
-            const history = new ChangeHistory(db, 'test');
+            const history = new ChangeHistory(db, 'test', 'sqlite');
             const statuses = await history.getAllStatuses();
             const status = statuses.get('test-with-failure');
 
@@ -273,7 +273,7 @@ describe('change: executor', () => {
             expect(result.status).toBe('failed');
 
             // Verify error is recorded in database
-            const history = new ChangeHistory(db, 'test');
+            const history = new ChangeHistory(db, 'test', 'sqlite');
             const statuses = await history.getAllStatuses();
             const status = statuses.get('test-error-recording');
 
@@ -299,7 +299,7 @@ describe('change: executor', () => {
             await executeChange(context, change2);
 
             // Query history
-            const history = new ChangeHistory(db, 'test');
+            const history = new ChangeHistory(db, 'test', 'sqlite');
             const statuses = await history.getAllStatuses();
 
             expect(statuses.size).toBe(2);
diff --git a/tests/core/change/tracker.test.ts b/tests/core/change/tracker.test.ts
index fa2c4eb9..37b3e7b4 100644
--- a/tests/core/change/tracker.test.ts
+++ b/tests/core/change/tracker.test.ts
@@ -54,7 +54,7 @@ describe('change: tracker', () => {
 
         await v1.up(db as Kysely<unknown>, 'sqlite');
 
-        tracker = new ChangeTracker(db, 'test');
+        tracker = new ChangeTracker(db, 'test', 'sqlite');
 
     });
 
diff --git a/tests/core/runner/dry-run-output.test.ts b/tests/core/runner/dry-run-output.test.ts
index 26274bbf..047372a2 100644
--- a/tests/core/runner/dry-run-output.test.ts
+++ b/tests/core/runner/dry-run-output.test.ts
@@ -16,7 +16,7 @@ import { join } from 'node:path';
 import { Kysely, SqliteDialect } from 'kysely';
 
 import { BunSqliteDatabase } from '../../../src/core/connection/dialects/sqlite-bun.js';
-import { runBuild } from '../../../src/core/runner/runner.js';
+import { runBuild, runFile } from '../../../src/core/runner/runner.js';
 import { v1 } from '../../../src/core/version/schema/migrations/v1.js';
 import type { NoormDatabase } from '../../../src/core/shared/index.js';
 import type { RunContext } from '../../../src/core/runner/types.js';
@@ -98,4 +98,39 @@ describe('runner: dry-run output', () => {
 
     });
 
+    it('should not execute the statement when runFile is given dryRun', async () => {
+
+        const filepath = join(sqlDir, '002_canary.sql');
+
+        await writeFile(filepath, 'CREATE TABLE dry_run_canary (id integer);', 'utf-8');
+
+        const result = await runFile(context(), filepath, { dryRun: true });
+
+        expect(result.status).toBe('success');
+
+        // The entire contract of --dry-run. `run build`/`run dir` honour it;
+        // `run file` accepted the flag and executed anyway, so a destructive
+        // file reviewed with --dry-run ran against the database.
+        const tables = await db.introspection.getTables();
+
+        expect(tables.map((t) => t.name)).not.toContain('dry_run_canary');
+
+    });
+
+    it('should write no tracking rows when runFile is given dryRun', async () => {
+
+        const filepath = join(sqlDir, '003_canary.sql');
+
+        await writeFile(filepath, 'CREATE TABLE tracked_canary (id integer);', 'utf-8');
+
+        await runFile(context(), filepath, { dryRun: true });
+
+        // executeFiles returns before it creates an operation; runFile must
+        // match, or a dry run leaves history claiming the file was applied.
+        const operations = await db.selectFrom('__noorm_change__').selectAll().execute();
+
+        expect(operations).toHaveLength(0);
+
+    });
+
 });