docs(cli): os migrate meta --from lists the mechanical edits, it does not rewrite your sources

.changeset/migrate-meta-lists-not-rewrites.md

@@ -0,0 +1,23 @@
+---
+"@objectstack/cli": patch
+---
+
+Correct a false verb in `os migrate meta`'s own source comments: the `--from`
+arm **lists** the mechanical edits an author's source needs; it rewrites no file
+(#10831).
+
+The `pendingDataMigrations` docblock in
+`packages/cli/src/commands/migrate/meta.ts` opened with "this command rewrites an
+author's source" — 74 lines above the command header that says the opposite
+("The command does not silently rewrite TS config source (that AST rewrite is
+unsafe and lossy)"). Both `writeFileSync` calls in the file are guarded by
+`if (flags.out)`, so the only file the `--from` arm ever writes is the `--out`
+JSON snapshot. The in-place codemod is a separate, unbuilt piece of work.
+
+The contrast the docblock was drawing — metadata migration's subject is the
+author's *source*, the two data migrations' subject is a deployment's *rows* —
+is correct and is preserved; only the verb on the first half changed. The
+`--stored` arm genuinely does rewrite `sys_metadata` rows and its wording is
+untouched.
+
+No runtime behaviour changes: comment-only.

content/docs/automation/flows.mdx

@@ -242,8 +242,9 @@ Replace them per branch — they are different mechanisms, not one rename:
 | `actionType: 'my_fn'` (shorthand) | `function: 'my_fn'` — the conversion moves it for you |
 | inline `config.script` | move the logic into a registered function and call it via `config.function` |
 
-Stored flows are rewritten by `os migrate meta --from 16`; authoring one of
-these keys in TypeScript is now a compile error carrying the same prescription.
+Run `os migrate meta --from 16` to list the mechanical edits for existing flow
+sources; apply them by hand. Authoring one of these keys in TypeScript is now a
+compile error carrying the same prescription.
 
 [#4343]: https://github.com/objectstack-ai/objectstack/issues/4343
 

content/docs/data-modeling/queries.mdx

@@ -385,8 +385,8 @@ backend, which left "what can this backend actually compute" unpredictable to th
 Both were retired (#6188, ADR-0049 enforce-or-remove): a query carrying either is now
 refused at parse with a prescription. There is no replacement in the query vocabulary —
 read the rows with an ordinary `fields` query and shape them in the caller, or materialise
-the roll-up as a stored field. `os migrate meta --from 16` rewrites affected dataset
-measures.
+the roll-up as a stored field. Run `os migrate meta --from 16` to list the mechanical
+edits for the affected dataset measures; apply them by hand.
 </Callout>
 
 <Callout type="info">

content/docs/deployment/cli.mdx

@@ -919,9 +919,9 @@ an old dialect exits `1`. So "my metadata is on protocol N" becomes a check
 rather than a belief.
 
 Note the division of labour with the default mode: `os migrate meta --from N`
-rewrites an **author's source** and reads no database; `--stored` rewrites **one
-deployment's rows** and reads no config. Same chain, opposite ends of the
-contract — which is why the two modes are mutually exclusive.
+lists the edits **an author's source** needs and reads no database; `--stored`
+rewrites **one deployment's rows** and reads no config. Same chain, opposite
+ends of the contract — which is why the two modes are mutually exclusive.
 
 **Without shell access, use the route.** This command needs to reach the
 deployment's database directly, which a hosted operator cannot do. The same pass

content/docs/protocol/objectql/query-syntax.mdx

@@ -857,7 +857,8 @@ by no SQL backend, so which backend could compute them was unpredictable to the
 Both were retired (#6188, ADR-0049 enforce-or-remove) and are now refused at parse with
 a prescription. There is no replacement in the query vocabulary — read the rows with an
 ordinary `fields` query and shape them in the caller, or materialise the roll-up as a
-stored field. `os migrate meta --from 16` rewrites affected dataset measures.
+stored field. Run `os migrate meta --from 16` to list the mechanical edits for the
+affected dataset measures; apply them by hand.
 </Callout>
 
 ### Group By Multiple Fields

packages/cli/src/commands/migrate/meta.ts

@@ -78,12 +78,12 @@ interface PendingDataMigration {
  * leaves for the operator (ADR-0104's 2026-07-30 addendum, #3438).
  *
  * Metadata migration and data migration are different jobs with different
- * subjects: this command rewrites an author's source, while these two rewrite
- * (or vouch for) a deployment's rows, one deployment at a time. Nothing here
- * can run them, and — with no database in reach — nothing here can say whether
- * they have run; the booting server reports that. What this can do is make
- * sure the upgrade never *ends* without naming them, because a gate nobody is
- * told about is served by nobody.
+ * subjects: this command reports the edits an author's source needs, while
+ * these two rewrite (or vouch for) a deployment's rows, one deployment at a
+ * time. Nothing here can run them, and — with no database in reach — nothing
+ * here can say whether they have run; the booting server reports that. What
+ * this can do is make sure the upgrade never *ends* without naming them,
+ * because a gate nobody is told about is served by nobody.
  *
  * Listed only when the author's own metadata declares the field classes each
  * gate is about, so the advice is never noise.