@@ -47,6 +47,24 @@ exact config, generator names and commands for this project; read it. The other
 | `references/typescript-templates.md` | declarative Mustache template-codegen in a TypeScript project |
 | `references/typescript-docs.md` | the docs generators (`docsFile`, `apiDocsFile`, `agentDocsFile`, `requirementsFile`, `metamodelDocsFile`, `docsSiteFile`) in a TypeScript project |
 
+## Upgrading a project from 1.0 to 1.1
+
+Read both guides before the first `gen` of an upgrade, for every port the project uses; the
+build can stay green while the result is wrong.
+
+- https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/physical-naming.md: the default column and table names are now `snake_case` in every
+  port (C#, Java, Kotlin's runtime and Python defaulted to the field names). A database whose
+  columns are named like its fields needs `"naming": { "columns": "literal" }` in
+  `.metaobjects/config.json`, or regenerated code queries columns that do not exist. The
+  per-port naming flags and generator args are removed.
+- https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/docs-are-generators.md: documentation is a generator in the project's list, and the docs
+  commands are removed.
+- **Resync the generators you own.** An ejected copy keeps the logic it was copied with, and a
+  plain `gen` does not refresh it. `meta eject --list` (`dotnet meta eject`, `metaobjects eject`,
+  `mvn metaobjects:eject`) reports each copy that differs from the reference;
+  `eject <name> --force` takes the new reference for a copy you never edited, and a copy you
+  edited is three-way merged instead. Steps for 1.0.x: https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/upgrading-within-1.0.md.
+
 ## Need an output? Write the generator — this is the primary path
 
 **When.** You need an output the model fully describes and no reference generator emits —
 
@@ -28,6 +28,24 @@ All artifacts share `groupId` `com.metaobjects` and one version property:
 | `metaobjects-maven-plugin` | the build-time codegen plugin |
 | `metaobjects-core-spring` | optional Spring wiring |
 
+## Column and table names
+
+**Column and table names come from `naming` in `.metaobjects/config.json`, the one setting
+every port reads** (ADR-0058): `meta migrate`, every port's codegen, and the OMDB runtime. The
+default is `snake_case`, what `meta migrate` creates. Through 1.0 this port defaulted to the
+field names; a database whose columns are named exactly like the fields declares it once:
+
+```json
+{ "schema_version": 1, "naming": { "columns": "literal" } }
+```
+
+There is no per-generator or runtime naming: the `columnNaming` generator arg fails
+`mvn metaobjects:generate`, and `SimpleMappingHandlerDB.setColumnNaming` throws. A Spring
+application that loads its metadata from the classpath points `metaobjects.physical-naming-config`
+at the project's `.metaobjects/config.json` packaged as a resource (for example
+`classpath:.metaobjects/config.json`). Details and the 1.0 to 1.1 steps:
+<https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/physical-naming.md>.
+
 ## Plugin config in `pom.xml`
 
 The plugin's `generate` goal binds to the `generate-sources` phase. Point its
 
@@ -45,6 +45,25 @@ plugin does not bring:
 Keep all four Exposed artifacts on one version. The port guide's `pom.xml` lists them
 with versions.
 
+## Column and table names
+
+**Column and table names come from `naming` in `.metaobjects/config.json`, the one setting
+every port reads** (ADR-0058): `meta migrate`, every port's codegen, and the Exposed tables the Kotlin generators write. The
+default is `snake_case`, what `meta migrate` creates. Through 1.0 the Kotlin runtime's JDBC side defaulted to the
+field names; a database whose columns are named exactly like the fields declares it once:
+
+```json
+{ "schema_version": 1, "naming": { "columns": "literal" } }
+```
+
+There is no per-generator or runtime naming: the `columnNaming` generator arg fails
+`mvn metaobjects:generate`, and `SimpleMappingHandlerDB.setColumnNaming` throws (the Exposed
+tables and the names generator already read the setting). A Spring
+application that loads its metadata from the classpath points `metaobjects.physical-naming-config`
+at the project's `.metaobjects/config.json` packaged as a resource (for example
+`classpath:.metaobjects/config.json`). Details and the 1.0 to 1.1 steps:
+<https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/physical-naming.md>.
+
 ## Plugin config in `pom.xml`
 
 The plugin's `generate` goal binds to the `generate-sources` phase. Point its
 
@@ -82,6 +82,8 @@ MetaObjects ships as separate packages per language on DIFFERENT version lines (
 
 `metamodelVersion` is also the number that tells you whether YOUR METADATA needs work, separately from the package version, which tells you whether your BUILD does. A package major means imports/CLI/generated-code shape may need attention; a metamodel major means your model may. A release can move one without the other — so when you upgrade, read the changelog for a metamodel-version move, not just the package number. For a 1.0.x → 1.0.x upgrade, follow https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/upgrading-within-1.0.md: it covers resyncing the generators you own (`meta eject --list`), which a plain `meta gen` does not do.
 
+**Upgrading from 1.0 to 1.1:** read both guides before you run `gen`, because the build can stay green while the result is wrong. https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/physical-naming.md: the default column and table names are now `snake_case` in every port, so a C#, Java, Kotlin or Python database whose columns are named like its fields needs `"naming": { "columns": "literal" }` in `.metaobjects/config.json`, or the regenerated code queries columns that do not exist. https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/docs-are-generators.md: documentation is a generator in the project's list, and the docs commands are removed. Then resync every generator you own (`meta eject --list` reports each copy that differs from the reference; `meta eject <name> --force` takes the new one, and a plain `meta gen` does not): an owned copy keeps the logic it was copied with.
+
 ## Going deeper (Claude Code)
 For authoring, codegen, runtime/UI, prompts, verify, or adoption-audit work, use the
 matching `metaobjects-*` skill — its body links the `references/<lang>.md` fragment
 
@@ -232,7 +232,7 @@ one-time fix.
 |---|---|---|
 | `--baseline=default` | all | the above: refuse what cannot be proved to be generated output |
 | `--baseline=adopt` | TS · Python · C# | record the files you HAVE as the merge base and **write nothing** |
-| `--baseline=fresh` | TS only | overwrite the refused files from fresh output and re-baseline (**discards** hand edits) |
+| `--baseline=fresh` | TS only | overwrite the refused files from fresh output and re-baseline (**discards** hand edits). A local snapshot body for a path the manifest has no record of is ignored, not merged against, so stale content from an earlier checkout is not kept as a hand edit |
 
 **`adopt` exists because the refusal's own remedy was unreachable.** It told you to commit
 `.hashes.json` — but nothing writes a manifest until a `gen` succeeds, and a run where
 
@@ -629,6 +629,12 @@ to the same paths as the 8.0 pom above:
 | the page header's project label, which was the module's `artifactId` | `projectName`, default `project`; set `${project.artifactId}` to keep 8.0's pages byte for byte |
 | `-Dmetaobjects.docs.*` properties | none; use Maven properties inside `<args>` if you need to override from the command line |
 
+**Remove any `columnNaming` generator arg from the same pom.** 8.1.0 refuses it, and the
+refusal points here because this is the pom you are editing. Column and table names are one
+setting now, `naming` in `.metaobjects/config.json`; if your database's columns are named
+exactly like your fields, add `"naming": { "columns": "literal" }` there. See
+[physical-naming.md](physical-naming.md), section "Java and Kotlin".
+
 **Give each api-docs entry an `outputDir` that holds generated files only.**
 `metaobjects:verify` now checks the pages, as it checks code: it regenerates each entry's
 `outputDir` and compares the whole tree, so a hand-written file there reads as stale.
 
@@ -3,7 +3,7 @@
 **Changed in:** 1.1.0 (Maven 8.1.0) · **Ports affected:** all five
 **Automatic fix:** none. Each section below is written so you, or a coding agent working in
 your repository, can make the change by hand. Decision record:
-[ADR-0058](../../../spec/decisions/ADR-0058-one-physical-naming-setting.md).
+[ADR-0058](https://github.com/metaobjectsdev/metaobjects/blob/main/spec/decisions/ADR-0058-one-physical-naming-setting.md).
 
 ## What changed
 
@@ -92,7 +92,7 @@ regenerate.
 | 1.0 | 1.1.0 |
 |---|---|
 | `metaobjects gen --column-naming <strategy>`, `metaobjects verify --codegen --column-naming <strategy>` | `"naming": { "columns": "<strategy>" }` in `.metaobjects/config.json`. The flag is refused (exit 2) |
-| `ObjectManager(..., column_naming="<strategy>")` | `ObjectManager(...)`. The manager reads the rule from the loaded root; the argument raises. A model loaded outside the project directory gets the project's rules with `attach_naming(root, project_dir)` from `metaobjects.naming`, which reads that project's `.metaobjects/config.json` |
+| `ObjectManager(..., column_naming="<strategy>")` | `ObjectManager(...)`. The manager reads the rule from the loaded root; the argument raises. A model loaded outside the project directory gets the project's rules with `attach_naming(root, project_dir)` from `metaobjects.naming`, which reads that project's `.metaobjects/config.json` and returns the root, so `root = attach_naming(root, project_dir)` |
 | no flag: `*_names.py` and the `ObjectManager` used the field names (`literal`) | no setting: snake_case. Add `"naming": { "columns": "literal" }` to keep 1.0's column names |
 
 `metaobjects verify --codegen` reports drift that another column rule, another table rule, or
 
@@ -47,6 +47,24 @@ exact config, generator names and commands for this project; read it. The other
 | `references/typescript-templates.md` | declarative Mustache template-codegen in a TypeScript project |
 | `references/typescript-docs.md` | the docs generators (`docsFile`, `apiDocsFile`, `agentDocsFile`, `requirementsFile`, `metamodelDocsFile`, `docsSiteFile`) in a TypeScript project |
 
+## Upgrading a project from 1.0 to 1.1
+
+Read both guides before the first `gen` of an upgrade, for every port the project uses; the
+build can stay green while the result is wrong.
+
+- https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/physical-naming.md: the default column and table names are now `snake_case` in every
+  port (C#, Java, Kotlin's runtime and Python defaulted to the field names). A database whose
+  columns are named like its fields needs `"naming": { "columns": "literal" }` in
+  `.metaobjects/config.json`, or regenerated code queries columns that do not exist. The
+  per-port naming flags and generator args are removed.
+- https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/docs-are-generators.md: documentation is a generator in the project's list, and the docs
+  commands are removed.
+- **Resync the generators you own.** An ejected copy keeps the logic it was copied with, and a
+  plain `gen` does not refresh it. `meta eject --list` (`dotnet meta eject`, `metaobjects eject`,
+  `mvn metaobjects:eject`) reports each copy that differs from the reference;
+  `eject <name> --force` takes the new reference for a copy you never edited, and a copy you
+  edited is three-way merged instead. Steps for 1.0.x: https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/upgrading-within-1.0.md.
+
 ## Need an output? Write the generator — this is the primary path
 
 **When.** You need an output the model fully describes and no reference generator emits —
 
@@ -28,6 +28,24 @@ All artifacts share `groupId` `com.metaobjects` and one version property:
 | `metaobjects-maven-plugin` | the build-time codegen plugin |
 | `metaobjects-core-spring` | optional Spring wiring |
 
+## Column and table names
+
+**Column and table names come from `naming` in `.metaobjects/config.json`, the one setting
+every port reads** (ADR-0058): `meta migrate`, every port's codegen, and the OMDB runtime. The
+default is `snake_case`, what `meta migrate` creates. Through 1.0 this port defaulted to the
+field names; a database whose columns are named exactly like the fields declares it once:
+
+```json
+{ "schema_version": 1, "naming": { "columns": "literal" } }
+```
+
+There is no per-generator or runtime naming: the `columnNaming` generator arg fails
+`mvn metaobjects:generate`, and `SimpleMappingHandlerDB.setColumnNaming` throws. A Spring
+application that loads its metadata from the classpath points `metaobjects.physical-naming-config`
+at the project's `.metaobjects/config.json` packaged as a resource (for example
+`classpath:.metaobjects/config.json`). Details and the 1.0 to 1.1 steps:
+<https://github.com/metaobjectsdev/metaobjects/blob/main/docs/features/migrations/physical-naming.md>.
+
 ## Plugin config in `pom.xml`
 
 The plugin's `generate` goal binds to the `generate-sources` phase. Point its