docs: write the 2.0.0 migration guide into the changelog

Assisted-by: GLM 5.3 Flash

CHANGELOG.md

@@ -229,6 +229,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a leading dot, `interpres: .port: ...`; the message now reads
   `interpres: port: ...`, the shape `EncodeError.Path` already used.
 
+### Migration from 1.x
+
+**The module path.** 2.0 lives at `sourcedock.dev/petrbalvin/interpres/v2`,
+the suffix the Go toolchain requires of every major version 2 module. Change
+every import and `go get` line:
+
+```sh
+go get sourcedock.dev/petrbalvin/interpres/v2
+```
+
+**TOML 1.1 only.** The acceptance contract is the TOML 1.1 corpus, and the
+promise that every 1.0 document parses exactly as before is withdrawn.
+Documents whose verdict changes are the ones 1.1 relaxed: `\e` and `\xHH`
+escapes, times without seconds, multi-line inline tables with comments and a
+trailing comma. Nothing that parsed in 1.x stops parsing, because the 1.1
+grammar contains the 1.0 one.
+
+**The output takes the 1.1 form.** A date-time writes seconds only when the
+value carries them, a fraction drops its trailing zeros, and a long inline
+table breaks across lines. A document written from the same value can come
+out shorter; it re-parses to the same value.
+
+**Text methods on by default.** A type implementing
+`encoding.TextMarshaler` or `encoding.TextUnmarshaler` now takes the text
+path with no option to switch it off. A struct that implemented the
+interface encodes as a string where it was a table before. `MarshalTOML` and
+`UnmarshalTOML` still win.
+
+**One Go type per date-time kind.** Offset date-times hand back
+`OffsetDateTime`, not a bare `time.Time`. Code that type-asserts the tree or
+expects `time.Time` inside `UnmarshalTOML` needs the new wrapper; a
+destination field of type `time.Time` keeps working.
+
+**The document carries what the map could not.** `Parse` returns a
+`*Document` with the key order, the inline distinction and the comments;
+`ParseMap` gives the plain `map[string]any` tree the old `Parse` returned.
+The document is writable, and `Marshal` writes it back with its comments.
+
+**Renamed API.** `Encoder.GroupByKind(bool)` is `Encoder.Layout(kind)` with
+`LayoutKindGrouped` (the old default) and `LayoutKindDeclaration` (the old
+`false`); `UseLiteralMultiline` is `LiteralMultiline`.
+
+**Tag options.** `omitempty` follows encoding/json: it now also drops empty
+strings, zero numbers, `false`, nil pointers and nil interfaces. `required`
+demands a key at decode. `inline` forces the inline table form at encode.
+`comment=text` carries a comment `EmitFieldComments` prints.
+
+**Errors.** `DecodeError.Path` is a `Path` (segments with a `String()`
+renderer), `EncodeError.Path` the same type instead of a plain string, and
+both messages render `interpres: server.ports[2]: ...` with one prefix.
+`SyntaxError` gained `Offset`, `Column` and `SourceLine`. Decode errors into
+a `Number`-carrying tree and the fixed-size array decode are new shapes a
+match on the old messages would not see.
+
+**Decoding shapes.** `map[string]any` values merge into a non-empty map
+destination; untagged embedded maps beyond the first stay empty; numbers can
+stay literals under `UseNumber`; local date-times can decode into
+`time.Time` under `LocalTimeLocation`. All three are opt-in or additive
+except where noted above.
+
 ## [1.1.0] - 2026-09-18
 
 ### Added