diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e1dcd1667..798c8b5f2b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **`annotations()` and `CATALOG.ANNOTATIONS`: domain model annotations in lint rules and the catalog** (ako/mxcli#1300, mendixlabs/mxcli#1309) — a microflow's annotations reached a rule through `activities_for()`, a domain model's through nothing, so a "no TODO notes" rule passed a domain model full of them. Each row has the module, the full caption with its newlines, and the place on the canvas. The schema moves to version 39, so a cached catalog is rebuilt once.
 - **An enumeration value's `id` in Starlark lint rules** (ako/mxcli#1301, mendixlabs/mxcli#1310) — `enumerations()` gave each value's caption in the default language only, and a rule could not tell which value a caption in another language belongs to. Each value now carries `id`, which is the `element_id` of its caption rows in `strings()`, so `getCaption(Module.Enum.Value)` can be resolved per language.
 - **`folders()` and `CATALOG.FOLDERS`: every folder, empty ones included** (ako/mxcli#1436, mendixlabs/mxcli#1538) — a rule could only derive a folder from the `folder` of a document in it, so "every module has the folders Objects and UI" reported an empty folder as missing. Each row has the module, the path (spelled as a document's `folder`), the parent path, the depth, and the documents and folders directly in it. `CATALOG.AGENTS` also parses now: like `FOLDERS`, its name is a keyword, and the `select` returned nothing without an error; a test now parses every name `show catalog tables` lists. The schema moves to version 38, so a cached catalog is rebuilt once.
+
+### Changed
+
+- **`docker build`, `docker run` and `docker reload` check and build the project as stored** (ako/mxcli#1794) — they ran `mx update-widgets` on their temporary copy first, so a project whose stored widget definitions are stale built, while `docker check`, `run --local` and Studio Pro all reported the CE0463s: the deployment was not built from what is committed. A stale widget now fails the build, each CE0463 labelled as one `mxcli fix widgets` clears or one that persists, as `docker check` labels them. `--update-widgets` builds a widget-normalised copy as before, leaving the project as it is; `--no-update-widgets` skips the labelling re-check.
+
+### Fixed
+
+- **A Data grid 2 or Gallery empty placeholder is documented, and refused where it cannot build** (ako/mxcli#1862, mendixlabs/mxcli#1704) — `emptyplaceholder { … }` was accepted by `check` and `exec`, and the page then failed `mx check` with CE0463 on the grid (11.14): the slot is hidden while `showEmptyPlaceholder` is `none`, its default. MDL-WIDGET10 now counts a filled slot as set, so `check` refuses widgets in a hidden slot and names the property; `mxcli syntax page.widgets` documents the working form (`showEmptyPlaceholder: 'custom'` with an `emptyplaceholder` block) and its `alter page` equivalent. It creates, alters and round-trips through `describe` unchanged.
+- **A page whose snippet call takes a parameter from an enclosing data container round-trips** (ako/mxcli#2055) — `describe` → `exec` of TestApp's `WorkflowCommons.ManageTaskAssignments` was refused ("snippet … requires parameter $Account"): Studio Pro stores the call with no parameter mappings and `mx check` accepts it, the parameter coming from a data view two containers out, while the builder looked only at the nearest container. It now accepts an omitted parameter that any enclosing data container supplies (the entity, a specialisation or a generalisation of it). The same page then built with CE1613 — `describe` printed a single association hop without its stored specialised destination (`TaskAssignmentHelper_User` arriving at `Administration.Account`, not `System.User`), so labels bound to `FullName` lost their attribute; such a hop now prints `Assoc/Destination`. The page now reports `Unchanged page` and `mx check` 0 errors (11.14).
+- **MOVE between modules rewrites access-rule XPaths and maps entity and nanoflow roles** (ako/mxcli#1836, mendixlabs/mxcli#1687) — splitting a module left an entity access rule's XPath naming the old module (`[Src.Order_Customer/Src.Customer/…]`: on 11.12.6, `mx check` reports CE1613 for the association and the entity), its access rules on the old module's roles, and a moved nanoflow's grants unmapped where a microflow's are mapped. The reference sweep now rewrites path steps — in XPaths and in expressions such as `$O/Src.Assoc/Name` — when the moved element is an entity or an association; an entity's access rules and a nanoflow's grants move to the target's same-named roles, and a role the target lacks is kept with a warning.
+- **A describe → create or replace round trip of an unchanged page no longer rewrites it** (ako/mxcli#1897) — on TestApp 15 of 68 pages reported `Replaced page` with nothing changed, for three things MDL cannot state: a tab container's default tab (stored null, written as the first tab — a stored second-tab default was also reset on every pass), an expression's trailing newline, and an empty screen-reader label Studio Pro stores as a client template. The write path now carries each from the stored element of the same `$ID`; all 15 report `Unchanged page`, and a real change still lands.
+- **Lint CONV013 no longer flags error handling that is the only valid choice** (ako/mxcli#1838, mendixlabs/mxcli#1689) — it reported Rollback on a call inside a loop, where Mendix allows only Rollback (CE0644, and `check` warns MDL006 on anything else), and on a call to a Java action that exists to throw, such as `CommunityCommons.ThrowException`, which is how a flow rolls itself back. Neither could be fixed, so every app needed a baseline entry. Both are no longer reported; other external calls are reported as before.
+- **`init --tool opencode` no longer puts every skill into every prompt** (ako/mxcli#1822, mendixlabs/mxcli#1683) — the generated `opencode.json` listed both skill trees as `instructions`, which OpenCode inlines whole: 150 files, 2.7 MB, about 73% of a 1M context window before the user typed anything. Its instructions are `AGENTS.md` alone; OpenCode discovers `.opencode/skills/` itself and loads a skill when its description matches. Those copies now keep the skill's own "Use when…" description, in one frontmatter block, instead of a second block described by the skill's title.
+
+## [0.31.0] - 2026-11-09
+
+Headline: **Publish your app's microflows as an MCP server, and keep secrets off the command line.** `create published mcp service` writes the MCP Server document Agent Editor starts at runtime, and agents gain tool approval, display text and streaming. The secret `run` flags and `--constant` take `@env:VAR` and `@file:path`, and the `brain` can be started before the project and edited in place. Alongside them come a long run of fixes that make `check --references` catch more of what the build would refuse, and `mxcli test --local` runs that start clean every time.
+
+### Added
+
 - **`create published mcp service` publishes the app's microflows as an MCP server** (ako/mxcli#2020) — the model configuration of MCP Server 5.x: an Agent Editor 2.6 `publishedMCPService` document that AgentEditorCommons starts at startup through `MCPServer.CreateMCPServer` and `AddTool`. `create [or modify]`, `alter … set / add tool / drop tool`, `describe`, `list published mcp services` and `drop`, with `tool name ( Microflow: …, Description: …, Title: …, Schema: … )` blocks and the OAuth settings (`AuthenticationEnabled`, `AuthenticationMicroflow`, `AuthorizationServerUrl`, `Scopes`). The server is served at `<app URL>/<EndpointPath>/mcp`; `ServerName`, which Studio Pro stores but its editor does not show, defaults to the document name and is kept when omitted on `create or modify`. A rewrite keeps the stored layout, each tool's `uuid` and every key mxcli does not model; `describe` → `exec` of the Studio Pro 11.16 sample writes nothing. `check` reports what `CreateMCPServer` would refuse at startup (MDL-MCPSERVER01): a reserved or sub-path `EndpointPath`, `Scopes` without an authorization server, an authorization server without an authentication microflow, a tool without a microflow.
 - **Tool approval, display text and streaming on an agent** (ako/mxcli#2021, ako/mxcli#2022) — Agent Editor's human-in-the-loop and streaming settings now have MDL. A `tool` or `mcp service` block takes `UserAccessApproval: HiddenForUser | VisibleForUser | UserConfirmationRequired`, `DisplayTitle` and `DisplayDescription`. A `knowledge base` block takes `MinSimilarity` and `IsVisible`. The agent takes `EnableBackendStreaming` and `EnableUIStreaming`; streaming is stored on the agent, not the model. `describe agent` prints them and `alter agent … set` sets the streaming switches. On `create or modify`, a setting the statement leaves out keeps its stored value. `describe` now prints an MCP tool as an `mcp service` block, where a `"mcp"`/`"MCP"` mismatch printed a generic `tool`. Measured on Studio Pro 11.12–11.16 documents.
 - **`mcp-server` skill: publish an app as an MCP server with runtime configuration** (part of ako/mxcli#2020) — the MCP Server module (3.x–4.x) publishes through a startup microflow calling `MCPServer.CreateMCPServer`, `AddTool` and `AddPrompt`, which MDL already writes as `call java action`. The skill gives the four microflows (authentication, tool, prompt, initialize) with their measured parameters and return types, and the per-version `ProtocolVersion` values; it was written into copies with MCP Server 4.0.0 and 5.4.0 (Mendix 11.16), where `mx check` reported nothing new. It also gives the 5.x OAuth parameters (`AuthorizationServerUrl`, `Scopes`, tool `Title`) and the 1:1 mapping onto Agent Editor's Published MCP service document, which AgentEditorCommons turns into the same Java action calls at startup.
@@ -24,20 +44,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **`--constant Module.Name=@env:VAR` and `=@file:path` keep a secret out of `ps` and shell history** (mendixlabs/mxcli#1765) — `mxcli run` and `mxcli test --local` read the value from an environment variable or from a file, so a token no longer has to be typed into the command line, which shows it in `ps` for as long as the app runs. An unset or empty variable and an empty file are errors, not an empty value; the owner-only check on a file is made on Unix and not on Windows; a relative `@file:` path is stored as an absolute one, so `run restart` works from another directory; a file readable by its group or by others is refused (`chmod 600`); one trailing newline is dropped. A value that really starts with `@` is written `@@…`. The run state keeps the `@env:`/`@file:` form, never the value.
 - **The secret `run` flags take `@env:VAR` and `@file:path`, so a password stays off the command line and `run restart` still works** (supersedes mendixlabs/mxcli#1761) — `--db-password`, `--db-admin-password`, `--screenshot-password`, `--hub-secret` and `--debug-pass` resolve a reference the way `--constant` does: an unset or empty variable, an empty file and a file its group or others can read are refused, naming the flag and the source, never the value. The reference, not the secret, is what `ps` shows and what `.mxcli/run-state.json` stores, so a run started with one can be `--detach`ed and `run restart`ed; each start resolves it again in its own environment, and a relative `@file:` path is stored as an absolute one. mendixlabs/mxcli#1761 proposed reading the password from stdin, which cannot be read again and so ruled out `--detach` and `run restart`; its fix for a flag value that looks like `-p` being dropped from the detached command is included.
 
+- **`brain` can start before the project, and entries can be edited, moved, sourced and listed** (ako/mxcli#1949, ako/mxcli#1950, ako/mxcli#1951, ako/mxcli#1952) — the brain's store now lives as long as the project does, from before it exists, and changes in place:
+  - `-C/--dir <dir>` names the brain's directory on every `brain` command, so you can fill a brain before its `.mpr` exists, and `mxcli new` adopts a target directory that holds only a brain. `brain init` no longer takes an argument it used to ignore.
+  - `brain edit <id> [<text>] [-a @Anchor]…` rewrites a staged or committed entry in place and keeps its id; `brain move <id> --slice <s>` moves a requirement to another slice.
+  - `capture --source <doc>[#<locator>]` and `edit --source` record which document an entry came from, and where in it. The path is stored relative to the project, so it works on other machines.
+  - `brain list [--slice] [--kind] [--open] [--json]` returns the committed store as data instead of rendered markdown, and reports malformed blocks rather than dropping them.
+- **`alter page set` reaches a Data grid 2 column's attribute and a text template's parameters** (ako/mxcli#1644, ako/mxcli#1966) — `set (Attribute: …) on <grid> column(…)` binds the column as `create` does (bare name, `Module.Entity.Attr` or an `Assoc/…/Attr` path). `set (CaptionParams: …)` on a button and `set (ContentParams: …)` on a dynamic text replace the template's parameters. Before this, you had to replace the whole widget.
+- **A queued call's retry policy in MDL** (ako/mxcli#1931) — `in queue … retry fixed|exponential (…)` writes `Queues$QueueFixedRetry` / `QueueExponentialRetry`; `describe` prints a stored retry so it round-trips, and `check` refuses `Retries: 0` (CE7044). A flow with a queued retry could not be rewritten before; a rewrite that would drop the stored retry is now refused.
+
 ### Changed
 
-- **`docker build`, `docker run` and `docker reload` check and build the project as stored** (ako/mxcli#1794) — they ran `mx update-widgets` on their temporary copy first, so a project whose stored widget definitions are stale built, while `docker check`, `run --local` and Studio Pro all reported the CE0463s: the deployment was not built from what is committed. A stale widget now fails the build, each CE0463 labelled as one `mxcli fix widgets` clears or one that persists, as `docker check` labels them. `--update-widgets` builds a widget-normalised copy as before, leaving the project as it is; `--no-update-widgets` skips the labelling re-check.
 - **A secret `run` flag value starting with `@` is refused unless it is `@env:`, `@file:` or `@@`** — `--db-password`, `--db-admin-password`, `--screenshot-password`, `--hub-secret` and `--debug-pass` follow the `--constant` rule; write `@@…` for a password that really starts with `@`.
 - **A `--constant` value starting with `@` is refused unless it is `@env:`, `@file:` or `@@`** (mendixlabs/mxcli#1765) — it used to be applied literally; now a mistyped `@evn:TOKEN` is not quietly used as the constant's value. Write `@@…` for a value that really starts with `@`.
 
 ### Fixed
 
-- **A Data grid 2 or Gallery empty placeholder is documented, and refused where it cannot build** (ako/mxcli#1862, mendixlabs/mxcli#1704) — `emptyplaceholder { … }` was accepted by `check` and `exec`, and the page then failed `mx check` with CE0463 on the grid (11.14): the slot is hidden while `showEmptyPlaceholder` is `none`, its default. MDL-WIDGET10 now counts a filled slot as set, so `check` refuses widgets in a hidden slot and names the property; `mxcli syntax page.widgets` documents the working form (`showEmptyPlaceholder: 'custom'` with an `emptyplaceholder` block) and its `alter page` equivalent. It creates, alters and round-trips through `describe` unchanged.
-- **A page whose snippet call takes a parameter from an enclosing data container round-trips** (ako/mxcli#2055) — `describe` → `exec` of TestApp's `WorkflowCommons.ManageTaskAssignments` was refused ("snippet … requires parameter $Account"): Studio Pro stores the call with no parameter mappings and `mx check` accepts it, the parameter coming from a data view two containers out, while the builder looked only at the nearest container. It now accepts an omitted parameter that any enclosing data container supplies (the entity, a specialisation or a generalisation of it). The same page then built with CE1613 — `describe` printed a single association hop without its stored specialised destination (`TaskAssignmentHelper_User` arriving at `Administration.Account`, not `System.User`), so labels bound to `FullName` lost their attribute; such a hop now prints `Assoc/Destination`. The page now reports `Unchanged page` and `mx check` 0 errors (11.14).
-- **MOVE between modules rewrites access-rule XPaths and maps entity and nanoflow roles** (ako/mxcli#1836, mendixlabs/mxcli#1687) — splitting a module left an entity access rule's XPath naming the old module (`[Src.Order_Customer/Src.Customer/…]`: on 11.12.6, `mx check` reports CE1613 for the association and the entity), its access rules on the old module's roles, and a moved nanoflow's grants unmapped where a microflow's are mapped. The reference sweep now rewrites path steps — in XPaths and in expressions such as `$O/Src.Assoc/Name` — when the moved element is an entity or an association; an entity's access rules and a nanoflow's grants move to the target's same-named roles, and a role the target lacks is kept with a warning.
-- **A describe → create or replace round trip of an unchanged page no longer rewrites it** (ako/mxcli#1897) — on TestApp 15 of 68 pages reported `Replaced page` with nothing changed, for three things MDL cannot state: a tab container's default tab (stored null, written as the first tab — a stored second-tab default was also reset on every pass), an expression's trailing newline, and an empty screen-reader label Studio Pro stores as a client template. The write path now carries each from the stored element of the same `$ID`; all 15 report `Unchanged page`, and a real change still lands.
-- **Lint CONV013 no longer flags error handling that is the only valid choice** (ako/mxcli#1838, mendixlabs/mxcli#1689) — it reported Rollback on a call inside a loop, where Mendix allows only Rollback (CE0644, and `check` warns MDL006 on anything else), and on a call to a Java action that exists to throw, such as `CommunityCommons.ThrowException`, which is how a flow rolls itself back. Neither could be fixed, so every app needed a baseline entry. Both are no longer reported; other external calls are reported as before.
-- **`init --tool opencode` no longer puts every skill into every prompt** (ako/mxcli#1822, mendixlabs/mxcli#1683) — the generated `opencode.json` listed both skill trees as `instructions`, which OpenCode inlines whole: 150 files, 2.7 MB, about 73% of a 1M context window before the user typed anything. Its instructions are `AGENTS.md` alone; OpenCode discovers `.opencode/skills/` itself and loads a skill when its description matches. Those copies now keep the skill's own "Use when…" description, in one frontmatter block, instead of a second block described by the skill's title.
 - **Building a flow no longer reads every microflow of the project once per called flow** (ako/mxcli#2043) — resolving a `call microflow` target looked its name up by reading and decoding every unit of the type, so one large flow in a large project took minutes, and outlasted the per-statement limit. A lookup now records where each name is and later reads that one unit, re-checking its name, type and module so a unit renamed or moved outside mxcli is not returned; a miss scans as before. On TestApp a flow calling 44 microflows builds in 0.29 s instead of 0.6 s; the saving grows with the number of flows in the project.
 - **A statement that times out or panics no longer crashes `exec` past its rollback** (ako/mxcli#2043, mendixlabs/mxcli#1780) — a statement that outlasted the per-statement limit kept running after `Execute` returned the timeout; `exec` then closed the project to roll back, the statement read through the closed reader, and the nil-pointer panic in its goroutine ended the process before the rollback and before the timeout was printed. The drop and every earlier statement stayed written. `Close` now waits (up to 2 minutes) for such a statement to stop, and a panic in any statement is that statement's error, so the script is rolled back as for any other failure.
 - **References to entities named as a type or reached through an association** (ako/mxcli#1829) — a flow whose action result, created list or Java/JavaScript entity-type argument names an entity, a snippet's parameters, and the entity an association path arrives at made no `refs` row, so `show references`, `impact` and the unused-entity check missed them (five entities in use on one project read as unreferenced), and an incremental build left a flow stale when an enumeration value it named was added. They are now `type`, `parameter`, `member` and `xpath` edges to the entity, and `value` to the enumeration when the value does not exist. Annotation and text prose and module-role names no longer produce member edges. Full catalog; the schema moves to version 37, so a cached catalog is rebuilt once.
@@ -91,6 +112,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **`mxcli test --watch` no longer shows a green run for a rebuild that failed** — when the rebuild after an edit failed (or the changed tests could not be parsed or injected), the loop printed the error and then ran the suite again at once, against the model from before the edit, so a broken microflow could pass. The round is now reported as an error row naming the step and the reason, in the terminal and in the JUnit file, the suite does not run, and the loop waits for the next change. The change baseline is taken when the change is detected, so a save made while the rebuild is failing starts a new round, and the "run #N" counter only advances for a round that ran. Ctrl-C after a failed change ends the watch with the red result, so the command exits non-zero. (mendixlabs/mxcli#1766)
 - **A copied app folder no longer inherits the original's run state, and run state no longer stores secrets** (mendixlabs/mxcli#1764) — `.mxcli/run-state.json`, `run-local.json` and `test-endpoint.json` record the project they were written for, but nothing compared it, so in a copy of a running app `mxcli run` refused to start and `mxcli run stop` signalled the original's process, and `mxcli test --attach` talked to the original's app. All three are now ignored when they name another project (symlinks resolved, case-folded on macOS and Windows); `run status` and `run stop` say that they ignored one. `--constant` values, the password flags and the `DatabasePassword` and `MicroflowConstants` runtime settings are no longer stored in `run-state.json`, and the dev-loop handshake no longer holds the resolved constants. The handshake file `run-local.json` still holds the database password (re-applying constants needs it); it is written owner-only (0600). **Behaviour change:** a run started with `--db-password` (or another inline secret) cannot be `run restart`ed; `run restart` says so and names the alternatives (the `PGPASSWORD` environment variable, or re-running `mxcli run` with the password) instead of starting the app with a placeholder. A run recorded from a devcontainer or WSL path is treated as another folder by the host side, so its state is ignored there.
 - **`mxcli test` failure line shows the actual value of an enumeration compare** (mendixlabs/mxcli#1763) — `@expect $Paid/Status = Procurement.InvoiceStatus.PAID` failed with only `expected …`, because the actual value was reported only when the operand type was known and an attribute path next to an enumeration value never was. An enumeration value on one side now pins the other, so the line reads `expected $Paid/Status = Procurement.InvoiceStatus.PAID, actual: APPROVED` (the enumeration key, via `toString()`).
+- **`mxcli test --local` no longer carries state or noise between runs** — a run of the suite now reports only what the suite did:
+  - Each run starts on an empty test database, on hsqldb and on PostgreSQL (where only the scratch `<app>_test` database is cleared, never the dev loop's) (ako/mxcli#1853).
+  - When `mxbuild --serve` stops answering, the boot restarts it and builds once more instead of failing with `context deadline exceeded`; a test that does not build has its errors repeated above the summary rather than lost among the "not run" rows (ako/mxcli#1834).
+  - No more `Module 'MxTest' already exists` on a clean project (ako/mxcli#1856), and no MDL-V1-SLASH / MDL-DEPR001 per test on a headerless suite (ako/mxcli#1855).
+- **`check --references` catches more of what `exec` or the build would refuse**:
+  - An image reference is matched case-sensitively, as Mendix does (a case difference is CE1613), and the hint names the stored spelling.
+  - `drop`, `rename` and `move` of a document that does not exist, and `alter enumeration` / `alter microflow` / `alter nanoflow` on one, are reported with the module's near names (ako/mxcli#1821).
+  - A `show page` passing a parameter that an earlier `alter page … add parameters` declared is accepted (ako/mxcli#1940).
+  - `alter page … set (DateFormat: Custom, CustomDateFormat: …)` is accepted in either order (ako/mxcli#1965).
+- **Page widgets that `mx check` refused** — a text template bound to an unset optional data source is stored as null, as Studio Pro does, and no longer CE0463 (ako/mxcli#1967). A `snippetcall` passing a data view's object names the widget instead of a page parameter the page lacks (CE0115) (ako/mxcli#1968). On a 9.x project, editing a pluggable widget keeps its Database source type instead of turning it into XPath (ako/mxcli#1208).
+- **Association paths are checked from the context entity** (ako/mxcli#834) — `database from $ctx/A1/A2` resolves multi-hop paths the way an association source does, and a hop that does not start at the context entity is refused instead of written as a step that cannot be followed.
+- **An import mapping rooted at a JSON array returns one object** (ako/mxcli#1938) — the import activity was written as returning a list, which mx check reported as CE0243.
+- **External entities keep their OData capabilities when `$metadata` aliases a vocabulary** (ako/mxcli#1977) — aliased Insert/Update/DeleteRestrictions and Core terms were skipped, so `create external entities` imported entities as not creatable or deletable (CE6630).
+- **Workflows on Mendix 9** — the user-task claim MDL-WORKFLOW10 suggests uses `System.WorkflowUserTask_Assignee` on Mendix 9 and `_Assignees` from 10.0 (ako/mxcli#1810). An annotation is written as `Workflows$Annotation`; the old storage name made Studio Pro throw `TypeCacheUnknownTypeException` (ako/mxcli#1784).
+- **`describe` output that did not re-execute** — a text holding `$$` (such as a JSON sample) is written as a string literal (ako/mxcli#1003). A message definition member is printed by the attribute it references after a rename, and `check` refuses a member naming an attribute the entity lacks (ako/mxcli#1935).
+- **`marketplace diff` and `update` no longer report every Java action of a protected module as changed** — the reference project now holds the package's Java and JavaScript sources, as `mx module-import` writes them.
+- **Lint MPR008 names the loop when a loop's box causes the overlap** (ako/mxcli#1839) — it gives the gap needed instead of asking for `@position` annotations that are already there.
+- **`mxcli syntax` documents every built-in expression function and every `drop` statement** (ako/mxcli#1866, ako/mxcli#1911) — the function list is rendered from the type checker's own signature table, so the reference and `check` agree.
 
 ## [0.30.0] - 2026-11-02
 
diff --git a/docs-site/src/SUMMARY.md b/docs-site/src/SUMMARY.md
index 43f78e7c9c..1390b86932 100644
--- a/docs-site/src/SUMMARY.md
+++ b/docs-site/src/SUMMARY.md
@@ -377,6 +377,7 @@
 # Blog
 
 - [Blog](blog/index.md)
+  - [Release: mxcli v0.31.0](blog/v0.31.0-release.md)
   - [Release: mxcli v0.30.0](blog/v0.30.0-release.md)
   - [Release: mxcli v0.29.0](blog/v0.29.0-release.md)
   - [Release: mxcli v0.28.0](blog/v0.28.0-release.md)
diff --git a/docs-site/src/blog/index.md b/docs-site/src/blog/index.md
index 5fa10e1bc8..bff4bd6f91 100644
--- a/docs-site/src/blog/index.md
+++ b/docs-site/src/blog/index.md
@@ -6,6 +6,7 @@ News, release announcements, and demos from the mxcli team.
 
 | Date | Post |
 |------|------|
+| November 9, 2026 | [Release: mxcli v0.31.0](v0.31.0-release.md) |
 | November 2, 2026 | [Release: mxcli v0.30.0](v0.30.0-release.md) |
 | October 30, 2026 | [Release: mxcli v0.29.0](v0.29.0-release.md) |
 | October 23, 2026 | [Release: mxcli v0.28.0](v0.28.0-release.md) |
diff --git a/docs-site/src/blog/v0.31.0-release.md b/docs-site/src/blog/v0.31.0-release.md
new file mode 100644
index 0000000000..08599baa37
--- /dev/null
+++ b/docs-site/src/blog/v0.31.0-release.md
@@ -0,0 +1,70 @@
+# Release: mxcli v0.31.0
+
+*November 9, 2026*
+
+v0.31.0 is about **publishing your app's microflows as an MCP server, and keeping secrets off the command line**.
+
+## What's new
+
+**Publish microflows as an MCP server.** `create published mcp service` writes the MCP Server 5.x document that Agent Editor starts when the app starts. Each `tool` block exposes one microflow to external agents:
+
+```sql
+create published mcp service AgentTest.CustomerMCP (
+  EndpointPath: 'customers',
+  Version: '1.0.0',
+  ProtocolVersion: v2025_03_26
+) {
+  tool count_customers (
+    Microflow: AgentTest.MCPTool_CountCustomers,
+    Description: 'Count the customers whose name starts with NamePrefix.',
+    Title: 'Count customers'
+  )
+};
+```
+
+The server is served at `<app URL>/customers/mcp`. `alter … add tool / drop tool`, `describe`, `list published mcp services` and `drop` complete the set, and the OAuth settings are there too. `check` reports what the server would refuse at startup: a reserved endpoint path, scopes without an authorization server, or a tool without a microflow. For MCP Server 3.x–4.x, the new `mcp-server` skill builds the same server from startup microflows.
+
+**Agents: tool approval and streaming.** Agent Editor's human-in-the-loop settings now have MDL. A tool can be hidden, shown, or require the user's confirmation (`UserAccessApproval`), with its own display title and description. Backend and UI streaming are switches on the agent. `check` also warns about a model or knowledge base `Provider` that Agent Editor would fail to import at startup.
+
+**Secrets stay off the command line.** The `run` password flags (`--db-password`, `--db-admin-password`, `--screenshot-password`, `--hub-secret`, `--debug-pass`) and `--constant` accept `@env:VAR` and `@file:path`:
+
+```bash
+mxcli run --local -p app.mpr \
+  --db-password @env:PGPASSWORD \
+  --constant MyModule.ApiKey=@file:$HOME/.secrets/api-key
+```
+
+`ps` shows the reference, and the run state stores the reference, not the value. A detached run can still be restarted with `run restart`, because each start reads the secret again. A file that its group or others can read is refused, so `chmod 600` it first.
+
+**A brain from day one.** A `brain` can now be started before its project exists (`-C <dir>`), and `mxcli new` adopts it. Entries can be edited and moved without changing their id, can record the document and lines they came from (`--source`), and `brain list --json` returns the committed store as data for tools to read.
+
+**More of the model from MDL.** This release adds:
+
+- `send external object` and `delete external object`, so a flow that holds them survives a describe-and-recreate.
+- *Associations to include* on a `call external action` argument.
+- A module's version and module type.
+- A queued call's retry policy.
+- `alter page set` for a Data grid 2 column's attribute and for a text template's parameters.
+
+**`check` catches more before the build.** A case difference in an image reference, a `drop` or `alter` of a document that doesn't exist, and many smaller cases that `exec` or mxbuild would refuse are now reported by `check --references`. `mxcli test --local` starts every run on an empty test database, recovers when `mxbuild --serve` stops answering, and repeats a failed build's errors above the summary line.
+
+## Upgrading
+
+Download the `v0.31.0` binary for your platform from the [release page](https://github.com/mendixlabs/mxcli/releases/tag/v0.31.0):
+
+```bash
+curl -fsSL -o mxcli \
+  https://github.com/mendixlabs/mxcli/releases/download/v0.31.0/mxcli-linux-amd64
+chmod +x mxcli && sudo mv mxcli /usr/local/bin/
+```
+
+Then refresh a project's skills and commands with `mxcli init --sync-skills`.
+
+Behaviour changes worth knowing:
+
+- A `--constant` value or a secret `run` flag that starts with `@` is refused unless it is `@env:`, `@file:` or `@@`. Write `@@…` for a value that really starts with `@`.
+- Run state (`.mxcli/run-state.json` and friends) no longer stores secrets, and an app folder you copy no longer inherits the original's run state.
+- `check --references` matches image names case-sensitively, as Mendix does. A script that relied on the old case-insensitive match now gets an error that names the stored spelling.
+- The catalog schema moves to version 34, so a cached catalog is rebuilt once.
+
+Full changelog: [CHANGELOG.md](https://github.com/mendixlabs/mxcli/blob/main/CHANGELOG.md)