@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'action-descriptor-resume-authority-default-flip',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a code
-  // span AND a table cell (see the note on `spec-type-alias-input-suffix-retired`).
   surface:
     'automation.ActionDescriptor.resumeAuthority — an OMITTED value on a pausing '
     + 'node descriptor (supportsPause: true, or any executor whose execute() returns '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'approval-escalation-enabled-default-flip',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a code
-  // span AND a table cell (see the note on `spec-type-alias-input-suffix-retired`).
   surface:
     'automation.ApprovalEscalation.enabled — an OMITTED value inside an approval '
     + "node's escalation block",
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'audit-log-action-enum-retired',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span AND a table cell.
   surface:
     "sys_audit_log.action — the values 'export' and 'permission_change' left the select "
     + 'enum declared by plugin-audit (packages/plugins/plugin-audit/src/objects/'
 
@@ -9,8 +9,6 @@ import type { SemanticMigration } from '../../types.js';
 // registry where a dropped entry produces no error anywhere.
 export const entry: SemanticMigration = {
   id: 'audit-log-action-restore-retired',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span AND a table cell.
   surface:
     "sys_audit_log.action — the value 'restore' left the select enum declared by "
     + 'plugin-audit (packages/plugins/plugin-audit/src/objects/sys-audit-log.object.ts). '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'driver-aggregate-undeclared-key-aliases-removed',
-  // No backticks in `surface`: the upgrade-guide renderer wraps this string
-  // in a code span of its own, and a nested pair renders as literal ticks.
   surface: "driver aggregate() call argument — query.aggregate and aggregations[].func",
   replacement:
     'query.aggregations and aggregations[].function — the spellings QueryASTSchema and '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'driver-sql-distinct-bare-filter-typed',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span already, and a nested backtick would close it.
   surface: 'SqlDriver.distinct() third argument — any value',
   replacement:
     'a bare FilterCondition (@objectstack/spec/data) — the same value find() carries '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'filter-regex-options-retired',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span already, and a nested backtick would close it.
   surface:
     'data.filter $regex / $options — in a STORED filter (dashboard widget filter and '
     + 'globalFilters, report runtimeFilter, page and component filter, solution-blueprint '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'import-run-automations-declared-default-corrected',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span AND a table cell (see the note on `spec-type-alias-input-suffix-retired`).
   surface:
     'api.ImportRequest runAutomations — the declared default of the key on BOTH import '
     + 'bodies, POST /api/v1/data/:object/import (ImportRequest) and its async twin POST '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'notification-list-cursor-retired',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span AND a table cell (see the note on `spec-type-alias-input-suffix-retired`).
   surface:
     'api.listNotifications cursor — the key on BOTH halves of GET /api/v1/notifications '
     + '(ListNotificationsRequestSchema and ListNotificationsResponseSchema) and the cursor '
 
@@ -4,8 +4,6 @@ import type { SemanticMigration } from '../../types.js';
 
 export const entry: SemanticMigration = {
   id: 'position-permissions-column-retired',
-  // No backticks in `surface` — build-upgrade-guide.ts renders it inside a
-  // code span AND a table cell.
   surface:
     'sys_position.permissions — the "JSON-serialized array of permission strings" '
     + 'textarea column left the platform position table declared by plugin-security '