docs: reconcile the value-shapes gate with the creation-attestation notes

#4215 landed #3438's third item (a store created from empty attests both
flags) while this branch was open, so the merged docs claimed "both flags"
without the second one ever being named.

- cli.mdx: the file migration's closing paragraph and writing-rules callout
  had been split off from their own section by the new one inserted above
  them; move them back so each command's rules sit under that command, and
  point the "other value classes keep warning" sentence at the gate that now
  exists for them.
- cli.mdx: the created-from-empty section offers an escape hatch per class,
  so it names both — the media one and the one this branch adds.
- v17.mdx: document `os migrate value-shapes` and why its flag is separate,
  and give the upgrade checklist its own bullet. The old wording told readers
  OS_DATA_VALUE_SHAPE_STRICT_ENABLED opts in "classes with no migration behind
  them", which stopped being true here.

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

Author: claude

content/docs/deployment/cli.mdx

@@ -660,6 +660,23 @@ Exit status is `0` only when the self-check passes, so CI can gate on it.
 | **Media value shapes** | A malformed `file` / `image` / `avatar` / `video` / `audio` value is **rejected** (`400 invalid_type`) instead of warned about. Set `OS_ALLOW_LAX_MEDIA_VALUES=1` to re-open leniency while diagnosing. |
 | **Released-file collection** | A field file whose one owning record lets go (the field is cleared or the record deleted) is tombstoned into the declared 30-day grace window; re-referencing the id within the window revives it, and after it the platform sweep reclaims the row and its bytes. Unverified deployments keep every released file forever. |
 
+Other value classes are unaffected: a `lookup` or `location` value keeps its own
+warn-first rollout until `os migrate value-shapes` (below) supplies *their*
+evidence, because this migration is evidence about *file* values and says
+nothing about theirs.
+
+<Callout type="warn">
+A dry run writes **nothing** — not the conversions, and not the flag either,
+even when the self-check would pass. `--apply` is the only writing mode. A
+later run that *fails* its self-check clears the flag's verified state, so a
+database that has drifted closes its own gate.
+
+A running server reads the flag once; after migrating, **restart it** for
+enforcement (and release-time tombstoning) to take effect. The sweep's final
+delete check re-reads the flag fresh, so a later failing run stops collection
+without a restart.
+</Callout>
+
 #### `os migrate value-shapes`
 
 The same gate for the **non-media** value classes — references (`lookup`,
@@ -703,21 +720,9 @@ know my data" lever, not the route to strictness — the route is running the
 migration that produces the evidence.
 </Callout>
 
-Other value classes are unaffected: a `lookup` or `location` value keeps its own
-warn-first rollout, because this migration is evidence about *file* values and
-says nothing about theirs.
-
-<Callout type="warn">
-A dry run writes **nothing** — not the conversions, and not the flag either,
-even when the self-check would pass. `--apply` is the only writing mode. A
-later run that *fails* its self-check clears the flag's verified state, so a
-database that has drifted closes its own gate.
-
-A running server reads the flag once; after migrating, **restart it** for
-enforcement (and release-time tombstoning) to take effect. The sweep's final
-delete check re-reads the flag fresh, so a later failing run stops collection
-without a restart.
-</Callout>
+Same writing rules as its sibling: a dry run writes **nothing**, `--apply` is
+the only writing mode, a later failing run clears the verified state, and a
+running server reads the flag once — **restart it** after a successful apply.
 
 #### A database created by this version needs no migration
 
@@ -735,8 +740,10 @@ attests nothing and produces its evidence by running the command, because
 
 Importing legacy values into such a deployment is rejected at the write path
 rather than silently accepted. That is the intended outcome; if you must admit
-them temporarily, `OS_ALLOW_LAX_MEDIA_VALUES=1` re-opens leniency, and
-re-running the migration re-establishes the flag from the data itself.
+them temporarily, `OS_ALLOW_LAX_MEDIA_VALUES=1` (media) and
+`OS_ALLOW_LAX_VALUE_SHAPES=1` (references and structured JSON) re-open leniency
+per class, and re-running the corresponding migration re-establishes its flag
+from the data itself.
 
 ### Scaffolding
 

content/docs/releases/v17.mdx

@@ -984,6 +984,23 @@ records** — never the platform version — is what authorises both strict medi
 value shapes and irreversible file collection. Upgrading changes neither;
 running the migration does.
 
+**The non-media classes have their own gate** (#3438) — references (`lookup`,
+`master_detail`, `user`, `tree`) and structured JSON (`location`, `address`,
+`composite`, `repeater`, `record`, `vector`):
+
+```bash
+os migrate value-shapes           # scan: reports, writes nothing
+os migrate value-shapes --apply   # scan, then record the flag if clean
+```
+
+A separate flag because it attests a separate fact: the file migration says file
+values were converted and their ownership reconciled, which tells you nothing
+about whether a `lookup` id or a `location` payload is well formed. This one
+converts nothing — a malformed `location` is application data only its author
+can correct — so it reports the object, field, type, count, sample record ids
+and parse issue, and you re-run until it is clean. `OS_ALLOW_LAX_VALUE_SHAPES=1`
+re-opens leniency while diagnosing.
+
 **A database created by 17 attests both flags at creation** (#3438), so a new
 deployment enforces from its first boot instead of waiting for someone to run a
 migration that, for an empty store, does nothing. The platform attests only a
@@ -1306,7 +1323,11 @@ objectui commits on top of the pin 16.1.0 shipped.
   media value shapes *and* released-file collection for this deployment, so
   read the report before you `--apply`. Do **not** reach for
   `OS_DATA_VALUE_SHAPE_STRICT_ENABLED` to get there: it opts every value class
-  in at once, including ones with no migration behind them.
+  in at once, regardless of which migrations this deployment has actually run.
+- **Reference and structured-JSON values:** run `os migrate value-shapes` and
+  fix what it reports before `--apply`. It converts nothing — the values it
+  names are application data — and a scan that was truncated or could not read
+  an object fails the gate even at zero violations.
 - **Datasources:** verify every declared datasource connects in every
   environment — a bound datasource that cannot connect now fails the boot
   instead of failing every later query.