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

* docs(cli): `os migrate meta --from` lists the edits, it does not rewrite (#10831)

Four hand-written docs-site pages and one docblock inside the command's own
source told authors that `os migrate meta --from N` rewrites their files. It
rewrites none. The `--from` arm replays the ADR-0087 chain over the loaded
stack in memory and reports the diff; both `writeFileSync` calls in
`packages/cli/src/commands/migrate/meta.ts` are guarded by `if (flags.out)`,
so the only file it ever writes is the `--out` JSON snapshot, and the command
header at :155-157 explicitly declines the AST rewrite as "unsafe and lossy".
The in-place codemod is separate and unbuilt.

Two of the four were wrong twice over: they attached a *stored*-arm behaviour
("stored flows are rewritten", "rewrite stored metadata automatically") to
`--from`, which is declared `exclusive: ['stored']` at :195-198 and therefore
cannot be combined with `--stored` at all. Both errors are fixed, not just the
verb, and "automatically" — the word the class-wide reword existed to remove —
is gone.

All four now carry the already-blessed sentence the generated reference
carriers use: run the command to LIST the mechanical edits for existing
sources, then apply them by hand.

The `pendingDataMigrations` docblock at :81 rides along per triage: the
contrast it draws (metadata migration's subject is the author's source, the
data migrations' subject is a deployment's rows) is correct and is preserved;
only the false verb on the first half changed.

Split on the ARM, not on the verb: `os migrate meta --stored --apply` genuinely
does rewrite `sys_metadata` rows, so no `--stored` wording was touched anywhere,
and `content/docs/releases/**` was not edited.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt

* docs(deployment): the `--from` half of cli.mdx's division-of-labour sentence lists, it does not rewrite

`content/docs/deployment/cli.mdx:921-924` is a fifth carrier of the same false
verb this PR exists to remove, and the card's table did not reach it:

    `os migrate meta --from N` rewrites an **author's source** and reads no
    database; `--stored` rewrites **one deployment's rows** and reads no config.

The `--from` half is false for the same reason as the other four — the arm
replays the chain in memory and prints the mechanical edits; both `writeFileSync`
calls in `packages/cli/src/commands/migrate/meta.ts` are guarded by
`if (flags.out)`, so the only file it writes is the `--out` JSON snapshot.

This is the same source-vs-rows contrast shape as the `meta.ts:81` docblock, so
it gets the same treatment triage ruled for that one: the contrast is correct and
is preserved verbatim — both bold subjects, "reads no database" / "reads no
config", and the mutual-exclusion note (which restates `exclusive: ['stored']`)
are untouched. Only the verb on the `--from` half changed.

Split on the ARM, not on the verb: the `--stored` half of this very sentence is
correct and is left exactly as it was, as are every other `--stored` mention on
the page (:624, :679, :850, :864-867). Line :838 already said "reports what is
left to do" and needed nothing.

Committed separately from the four dispatched pages so it can be dropped on its
own if review judges it out of scope.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DdCnBGcHeufjrq7drTD3wt

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.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.