@@ -0,0 +1,14 @@
+---
+'@objectstack/cli': patch
+---
+
+feat(cli): `os migrate audit-key-material` removes the encrypted key-material columns from the audit-ledger copies 18.2.0 and earlier wrote
+
+Clause-②: no
+Metadata-protocol: none
+
+**Run `os migrate audit-key-material --apply` once after upgrading from 18.2.0 or earlier.** The audit writer no longer copies the encrypted key-material column of a secret-store or settings row into `sys_audit_log` (`new_value`, `old_value`) or `sys_activity` (both halves of `metadata`). Copies written before that still carry it.
+
+- **The command.** `os migrate audit-key-material` removes those columns with the writer's own helper, through `@objectstack/plugin-audit`'s `migrateKeyMaterialCopies` (the hot tables) and `migrateArchivedKeyMaterialCopies` (the archive datasource `sys_audit_log` archives to). It is a dry run by default (counts, writes no row), `--apply` writes, and its flags are `os migrate audit-mail-bodies`'s, one for one (`--database-url`, `--apply`, `--yes`, `--force`, `--json`). The report is counts only, per table, and never prints a value.
+- **What changes in a row.** Only the key-material keys of the copy are removed. Every other key of the copy and every other column of the row stay byte-identical, the row's `updated_at` included. A column of the same name in a copy of any other object is left alone.
+- **Idempotent.** A copy without the columns has nothing to remove, so a second run rewrites nothing; re-running finishes an interrupted run. A failed read or write exits `1`, and so does an archive datasource the run could not examine (`not-connected` / `unknown` in the `--json` document's `archive` entries, as for `audit-mail-bodies`).
@@ -1293,6 +1293,7 @@ where the data lives.
 | `os migrate organization-ownership` | The v18 ownership ceremony (ADR-0131 D10): write a plan of what each table's rows will become, then `--apply` that reviewed plan. It upgrades a database 17.x or an 18.0 pre-release (`18.0.0-next.*`) created; a v18 server refuses to start on one until it has run. See [below](#os-migrate-organization-ownership) |
 | `os migrate activity-changed-fields` | Stamp the two read-rule columns (`changed_fields`, `milestone_key`) on the `sys_activity` rows written before they existed. Until it runs, those rows are withheld from every reader but the system, so run it at once after upgrading. No flag; idempotent |
 | `os migrate audit-mail-bodies` | Mask the mail bodies (`body_text`, `body_html`) that `sys_audit_log` and `sys_activity` copies of `sys_email` / `sys_identity_email` rows still hold in clear, written before the audit writer masked them. Covers the `archive` datasource `sys_audit_log` archives to as well. Reports counts only. No flag; idempotent. See [below](#os-migrate-audit-mail-bodies) |
+| `os migrate audit-key-material` | Remove the encrypted key-material columns from the `sys_audit_log` and `sys_activity` copies written before the audit writer omitted them. Covers the `archive` datasource `sys_audit_log` archives to as well. Reports counts only. No flag; idempotent. See [below](#os-migrate-audit-key-material) |
 | `os migrate comment-parent-pair` | Stamp the parent pair (`object_name`, `record_id`) on the `sys_comment` rows written before it existed. Until it runs, a broad comment read past 2,000 candidate rows omits comments the reader may see, and its total agrees with the short list, so run it at once after upgrading. No flag; idempotent |
 | `os migrate meta --stored` | Replay the metadata conversion chain over this deployment's `sys_metadata` rows and rewrite the ones still carrying a pre-protocol shape. Hygiene, not a gate — nothing depends on it having run |
 | `os migrate security-catalog-overlays` | List the environment-wide permission-set and position rows (the legacy plurals `permissions` / `positions` included) stored over a name a configured package holds — the rows a v18 cold boot refuses — each with the package that holds its name; `--apply` deletes them, one history tombstone per row. Run it before the first v18 boot, with the flags and environment the deployment boots with: the platform security plugin's sets are held only where `os serve` composes it (an auth secret set, and the `auth` tier on), and the step takes `serve`'s `--preset` and `--dev` with `serve`'s meaning. Adopts nothing; exits 1 while it lists a row |
@@ -1311,7 +1312,7 @@ holds nothing, and answers with empty work and exit 0. `os migrate value-shapes`
 clean over zero records and names the objects it did not read. `os migrate
 recorded-by` has nothing to convert and `os migrate resume` no interrupted runs.
 `os migrate meta --stored` has no stored metadata to examine, `os migrate
-audit-metadata-bodies` and `os migrate audit-mail-bodies` no audit copy to rewrite, and
+audit-metadata-bodies`, `os migrate audit-mail-bodies` and `os migrate audit-key-material` no audit copy to rewrite, and
 `os migrate account-issuer` no account to collide. `os secret orphans`, `os secret rewrap` and `os storage orphans`
 report no secret and no file. A read the command cannot avoid and that fails for any
 other reason still refuses and exits 1. Point `--database-url` at the deployment's
@@ -1639,6 +1640,40 @@ An archive that a host registers in code outside the stack config (a plugin
 that publishes the driver itself) is not reached and reads `none`. To mask it,
 declare it in the stack config's `datasources` with `autoConnect: true`.
 
+#### `os migrate audit-key-material`
+
+The audit trail keeps a copy of each audited row: `sys_audit_log` in
+`new_value` / `old_value`, and the activity feed in both halves of
+`sys_activity.metadata`. For the secret store and the two settings holders,
+that copy used to carry the row's encrypted key-material column. New copies
+omit those columns. This command removes them from the copies written before
+that.
+
+```bash
+os migrate audit-key-material                    # Dry run: counts, writes no rows
+os migrate audit-key-material --apply            # Remove the columns (prompts)
+os migrate audit-key-material --apply --yes --json   # CI / scripts
+```
+
+Only the key-material keys of the copy are removed: every other key of the copy
+(which record, its key id, algorithm and version), and every other column of the
+row (its `updated_at` included), stays as it was. A column of the same name in a
+copy of any other object is left alone. The report holds counts only and never
+prints a value. The flags are `os migrate audit-mail-bodies`'s, one for one.
+
+**Idempotent**: a copy without the columns has nothing to remove, so a second
+run rewrites nothing, and re-running is how an interrupted run is finished. A
+failed read or write exits `1`. Run it once after upgrading, with the server
+stopped, or re-run it once and read 0.
+
+**The archive datasource too**, exactly as for
+[`os migrate audit-mail-bodies`](#os-migrate-audit-mail-bodies): after the hot
+run, the command runs the same rewrite over the datasource `sys_audit_log`
+archives to, in the same dry-run or `--apply` mode, and its `--json` document
+carries the same `archive` entries with the same `status` values and exit
+codes. A declared archive this boot does not connect, or an active runtime
+datasource row of that name, reads `not-connected` and exits `1`.
+
 #### `os migrate organization-ownership`
 
 The v18 ownership ceremony (ADR-0131 D10), and the upgrade path of a database
 
@@ -480,6 +480,8 @@ the protocol-18 step, which `os migrate meta --from 17` lists for your sources
 | v12.0.0 | [Upgrade checklist](/docs/releases/v12#upgrade-checklist) |
 | v9.0.0 | [Upgrade checklist](/docs/releases/v9#upgrade-checklist) |
 
+**Upgrading from 18.2.0 or earlier:** run [`os migrate audit-key-material`](/docs/deployment/cli#os-migrate-audit-key-material) once, a dry run first and then `--apply`; it removes the encrypted key-material columns from the audit-ledger copies those releases wrote.
+
 The v17 and v18 lines are broken out per release. Each v17 minor shipped
 breaking changes under the repo's launch-window convention — which ships a
 breaking change as `minor` rather than `major`, so the version number is not the