@quonfig/cli 0.0.49 → 0.0.51

package/dist/init/templates.js

@@ -25,22 +25,50 @@ This is a [Quonfig](https://quonfig.com) workspace repository. All configuration
 | \`schemas/\` | JSON Schemas that configs can reference for validation |
 | \`schemas-protected/\` | Admin-only schemas |
 
-## Quick start
+## Quick start (works fully offline — no account required)
+
+This workspace is just a git repo full of JSON files. You can edit those files
+directly, validate them locally, and point any Quonfig SDK at this directory.
+No login, no API call, no internet connection needed.
 
 \`\`\`bash
-# Validate the workspace
+# 1. Edit a flag — see the sample files in feature-flags/ for the shape.
+$EDITOR feature-flags/my.new.flag.json
+
+# 2. Validate the workspace.
 qfg verify
 
-# Create a new feature flag
-qfg create my.new.flag --type=boolean-flag
+# 3. (Optional) Generate TypeScript types for your app.
+qfg generate
 
-# List all configs
-qfg list
+# 4. Commit. The pre-commit hook re-runs qfg verify automatically.
+git add . && git commit -m "Add my.new.flag"
 \`\`\`
 
+## Two ways to use this repo
+
+**Open-source / fully local.** Edit JSON, run \`qfg verify\`, point your SDK
+at this directory (\`datadir: "./quonfig"\`). Push the repo wherever you want
+(GitHub, self-hosted Gitea, your own server). This is the no-account path.
+
+**Hosted Quonfig.** If you also have a Quonfig account, server-side commands
+like \`qfg push\`, \`qfg create\`, \`qfg list\`, \`qfg set-default\`, and
+\`qfg get\` give you a UI, real-time SSE delivery to SDKs, evaluation
+telemetry, and audit history. These all require \`qfg login\`.
+
+## Local-only commands (no login required)
+
+| Command | What it does |
+|---------|--------------|
+| \`qfg init\` | Re-initialize this workspace (idempotent, refreshes templates) |
+| \`qfg verify\` | Validate every JSON file against the schema and cross-file rules |
+| \`qfg generate\` | Generate typed SDK client code from the configs in this dir |
+| \`qfg config-schema\` | Print the canonical config schema (great for AI agents) |
+| \`qfg migrate\` | Import flags from LaunchDarkly, Flagsmith, etc. |
+
 ## Schema
 
-Config files reference the hosted JSON Schema at <https://api.quonfig.com/schemas/v1/stored-config.json> via their \`$schema\` field. Editors that support JSON Schema will provide autocomplete and validation automatically.
+Config files reference the hosted JSON Schema at <https://api.quonfig.com/schemas/v1/stored-config.json> via their \`$schema\` field. Editors that support JSON Schema will provide autocomplete and validation automatically. The schema URL is fetched once by your editor's LSP — the CLI and SDK don't need it.
 
 ## Validation
 
@@ -55,7 +83,24 @@ export function claudeMdTemplate() {
 
 This is a Quonfig workspace repository. Configuration is stored as JSON files in git.
 
-**After every change to this repo, run \`qfg verify\` to validate.**
+## How to work in this repo
+
+**You edit JSON files directly.** Do not run \`qfg create\`, \`qfg set-default\`,
+\`qfg set-rollout\`, \`qfg override\`, \`qfg push\`, \`qfg pull\`, \`qfg get\`,
+or \`qfg list\` — those commands talk to a hosted Quonfig server. In a local
+workspace, the source of truth is this git repo, so edit JSON in place.
+
+The complete local-only toolkit:
+
+| Command | When to use |
+|---------|-------------|
+| \`qfg verify\` | After every change. Validates schema + cross-file rules. |
+| \`qfg config-schema\` | Print the canonical schema. Use this to look up field names, operator enums, value-type shapes before you write a new config. |
+| \`qfg generate\` | Regenerate typed SDK client code (consumers ask for this; you usually won't need to run it unless asked). |
+| Read existing files | Look at sibling JSON files in the same directory for the canonical shape before writing a new one. |
+
+**After every change to this repo, run \`qfg verify\` to validate.** If it
+fails, fix the JSON until it passes — do not ship a broken workspace.
 
 ## JSON Schema
 
@@ -144,10 +189,12 @@ This is a Quonfig workspace repository. See \`CLAUDE.md\` for the complete schem
 
 ## Key rules
 
-1. **Always validate**: run \`qfg verify\` after any change to this repo.
-2. Filename must match the \`key\` field (e.g. \`my.flag.json\` has \`"key": "my.flag"\`).
-3. Files must be in the correct directory for their \`type\`.
-4. See \`CLAUDE.md\` for the full list of value types, operators, and constraints.
+1. **Edit JSON files directly.** Do NOT use \`qfg create\`, \`qfg set-default\`, \`qfg push\`, \`qfg get\`, or \`qfg list\` — those require a hosted Quonfig account. The source of truth here is the git repo.
+2. **Always validate**: run \`qfg verify\` after any change to this repo.
+3. **Look before you leap**: read sibling JSON files for the canonical shape, and run \`qfg config-schema\` to confirm field names, operator enums, and value types before writing a new config.
+4. Filename must match the \`key\` field (e.g. \`my.flag.json\` has \`"key": "my.flag"\`).
+5. Files must be in the correct directory for their \`type\`.
+6. See \`CLAUDE.md\` for the full list of value types, operators, and constraints.
 `;
 }
 // ── Pre-commit hook ────────────────────────────────────────────────────

package/dist/migrate/local-write.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
-import { writeMigrationReport } from './migration-report.js';
+import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { detectDuplicateKeys } from './sources/launch/translate.js';
 import { MIGRATOR_IDENTITY, stackCommits } from '../util/clone-and-stack-push.js';
 import { runGit, spawnGit } from '../util/git-ops.js';
@@ -199,16 +199,21 @@ export const applyLocalMigration = async (opts) => {
     const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
     const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
     const conversionNotes = opts.source.getConversionNotes?.() ?? null;
+    const environmentMap = opts.source.getEnvironmentMap?.() ?? null;
+    const maintainerMap = opts.source.getMaintainerMap?.() ?? null;
     const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
     const skippedTotal = (skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
     const counts = buildMigrationCounts(livePaths, opts.environments.length, skippedTotal);
     const reportData = {
         ...opts.reportData,
         counts,
+        ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
+        followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
         ...(coercedSentinels ? { coercedSentinels } : {}),
         ...(conversionNotes && conversionNotes.length > 0 ? { conversionNotes } : {}),
         ...(droppedOverrides ? { droppedOverrides } : {}),
         ...(duplicateResolutions ? { duplicateResolutions } : {}),
+        ...(maintainerMap && Object.keys(maintainerMap).length > 0 ? { maintainerMap } : {}),
         ...(skippedConfigs ? { skippedConfigs } : {}),
     };
     writeMigrationReport(opts.localDir, reportData);
@@ -331,6 +336,8 @@ export const buildAuditFinalCommit = (opts) => ({
         const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
         const coercedSentinels = opts.source.getCoercedSentinels?.() ?? null;
         const conversionNotes = opts.source.getConversionNotes?.() ?? null;
+        const environmentMap = opts.source.getEnvironmentMap?.() ?? null;
+        const maintainerMap = opts.source.getMaintainerMap?.() ?? null;
         const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
         removeQfFromGitignore(dir);
         writeImportState(dir, opts.importState);
@@ -339,10 +346,13 @@ export const buildAuditFinalCommit = (opts) => ({
         const reportData = {
             ...opts.reportData,
             counts,
+            ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
+            followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
             ...(coercedSentinels ? { coercedSentinels } : {}),
             ...(conversionNotes && conversionNotes.length > 0 ? { conversionNotes } : {}),
             ...(droppedOverrides ? { droppedOverrides } : {}),
             ...(duplicateResolutions ? { duplicateResolutions } : {}),
+            ...(maintainerMap && Object.keys(maintainerMap).length > 0 ? { maintainerMap } : {}),
             ...(skippedConfigs ? { skippedConfigs } : {}),
         };
         writeMigrationReport(dir, reportData);

package/dist/migrate/migration-report.d.ts

@@ -1,6 +1,7 @@
 import type { IdentifierMap } from './identifier-map.js';
 import type { ConversionNote } from './quonfig-target/report.js';
-import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, SkippedConfigSummary } from './source.js';
+import type { CoercedSentinelSummary, DroppedOverrideSummary, DuplicateResolutionSummary, EnvironmentMapEntry, SkippedConfigSummary } from './source.js';
+export type { EnvironmentMapEntry } from './source.js';
 export interface MigrationReportCounts {
     configsMigrated: number;
     environmentsMapped: number;
@@ -23,10 +24,6 @@ export interface UnsupportedFeature {
     feature: string;
     note?: string;
 }
-export interface EnvironmentMapEntry {
-    quonfigName: string;
-    sourceName: string;
-}
 export interface FollowUpChecklist {
     mustFixBeforeCutover: string[];
     reviewPostCutover: string[];
@@ -65,6 +62,14 @@ export interface MigrationReportData {
     followUp: FollowUpChecklist;
     identifierMap: IdentifierMap;
     lossyMappings: LossyMapping[];
+    /**
+     * qfg-l8uz: source maintainerId → email pairs. Rendered as a sub-table on
+     * `## Identifier map` so the reader sees who owned each dropped-maintainer
+     * note, and consumed by the renderer to decorate the dropped-maintainer
+     * rollup with emails. Optional/undefined when the source has no member
+     * lookup (or it failed) — both the table and the decoration just no-op.
+     */
+    maintainerMap?: null | Record<string, string>;
     /**
      * Configs soft-skipped by translate() because the source data was invalid
      * (e.g. variant/valueType mismatch). Null when nothing was skipped.
@@ -73,6 +78,12 @@ export interface MigrationReportData {
     source: string;
     unsupportedFeatures: UnsupportedFeature[];
 }
+/**
+ * Folds conversion notes into a followUp checklist. De-duplicates by hint
+ * string so a flag with two dropped prerequisites doesn't produce two
+ * identical checkbox lines.
+ */
+export declare const deriveFollowUpFromConversionNotes: (base: FollowUpChecklist, notes: ConversionNote[] | undefined) => FollowUpChecklist;
 export declare const buildMigrationReport: (data: MigrationReportData) => string;
 export declare const migrationReportPath: (outputDir: string) => string;
 export declare const writeMigrationReport: (outputDir: string, data: MigrationReportData) => string;

package/dist/migrate/migration-report.js

@@ -43,14 +43,34 @@ const renderEnvironmentMap = (entries) => {
     const rows = sorted.map((e) => `| ${e.sourceName} | ${e.quonfigName} |`);
     return [header, '', '| Source | Quonfig |', '| --- | --- |', ...rows].join('\n');
 };
-const renderIdentifierMap = (map) => {
+const renderIdentifierMap = (map, maintainerMap) => {
     const header = '## Identifier map';
+    const sections = [];
     const keys = Object.keys(map);
-    if (keys.length === 0)
+    if (keys.length > 0) {
+        const sorted = [...keys].sort();
+        const rows = sorted.map((k) => `| \`${k}\` | \`${map[k]}\` |`);
+        sections.push(['### Legacy keys', '', '| Legacy key | Quonfig key |', '| --- | --- |', ...rows].join('\n'));
+    }
+    const maintainerIds = maintainerMap ? Object.keys(maintainerMap) : [];
+    if (maintainerIds.length > 0) {
+        const sorted = [...maintainerIds].sort();
+        const rows = sorted.map((id) => `| \`${id}\` | ${maintainerMap[id]} |`);
+        sections.push([
+            '### Maintainer IDs',
+            '',
+            `Resolved **${sorted.length}** maintainer ID${sorted.length === 1 ? '' : 's'} via the LaunchDarkly /members ` +
+                `endpoint. Use this table to read 'Dropped maintainer metadata' below — each \`maintainerId\` there maps to the ` +
+                `email here.`,
+            '',
+            '| maintainerId | email |',
+            '| --- | --- |',
+            ...rows,
+        ].join('\n'));
+    }
+    if (sections.length === 0)
         return `${header}\n\n${NONE}`;
-    const sorted = [...keys].sort();
-    const rows = sorted.map((k) => `| \`${k}\` | \`${map[k]}\` |`);
-    return [header, '', '| Legacy key | Quonfig key |', '| --- | --- |', ...rows].join('\n');
+    return [header, '', ...sections].join('\n\n');
 };
 const renderDroppedOverrides = (dropped) => {
     if (!dropped || dropped.total === 0)
@@ -90,20 +110,34 @@ const renderDuplicateResolutions = (resolved) => {
     }
     return lines.join('\n');
 };
-const renderCoercedSentinels = (coerced) => {
+const FLAGSMITH_ENV_BUCKET_LABEL = {
+    '_all-envs': 'Override rows (all environments)',
+    '_cross-env': 'Cross-environment value-type divergence (no single env owns this)',
+};
+const renderCoercedSentinels = (coerced, source) => {
     if (!coerced || coerced.total === 0)
         return null;
     const envIds = Object.keys(coerced.byEnv).sort();
-    const lines = [
-        '## Coerced sentinel rule values',
-        '',
-        `Coerced **${coerced.total}** rule value(s) from Launch's "no value set yet" sentinel ({type:"string", value:""}) to the typed default for the surrounding config. The qfg-verify hook would otherwise reject these as type-mismatches and fail-stop the entire push. Affected envs: **${envIds.length}**. Review each and set a real default in the source system if needed.`,
-    ];
+    const intro = source === 'flagsmith'
+        ? `Coerced **${coerced.total}** rule value(s) from Flagsmith's runtime semantics into a concrete served value. ` +
+            `Two flavors are bucketed here:\n\n` +
+            `1. **D-F1: \`enabled=false\` on non-boolean features.** Flagsmith would have ignored the stored value and ` +
+            `served your code's hardcoded default. Quonfig always serves a value, so the migrator emits the stored ` +
+            `\`feature_state_value\` and surfaces every affected flag below.\n` +
+            `2. **D-F5: cross-environment value-type divergence.** Flagsmith allowed the same flag to be a string in one ` +
+            `env and an int in another; Quonfig requires one \`valueType\` per flag. The migrator coerced to \`string\`.\n\n` +
+            `Review each entry below and set a real default in the source system if the value is wrong.`
+        : `Coerced **${coerced.total}** rule value(s) from Launch's "no value set yet" sentinel ` +
+            `({type:"string", value:""}) to the typed default for the surrounding config. The qfg-verify hook would ` +
+            `otherwise reject these as type-mismatches and fail-stop the entire push. Affected envs: ` +
+            `**${envIds.length}**. Review each and set a real default in the source system if needed.`;
+    const lines = ['## Coerced sentinel rule values', '', intro];
     for (const envId of envIds) {
         const perFlag = coerced.byEnv[envId];
         const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
         const flagCount = Object.keys(perFlag).length;
-        lines.push('', `### env-${envId} — ${totalForEnv} coerced from ${flagCount} config(s)`, '');
+        const heading = FLAGSMITH_ENV_BUCKET_LABEL[envId] ?? `env-${envId}`;
+        lines.push('', `### ${heading} — ${totalForEnv} coerced from ${flagCount} config(s)`, '');
         const sorted = Object.keys(perFlag).sort();
         for (const flagPath of sorted) {
             lines.push(`- \`${flagPath}\` (${perFlag[flagPath]})`);
@@ -135,24 +169,112 @@ const renderSkippedConfigs = (skipped) => {
  */
 const CONVERSION_NOTE_HEADINGS = {
     'ai-config-skipped': 'AI Configs skipped (out of v1 scope)',
+    'cross-env-value-type-coerced': 'Cross-environment value-type coerced to string',
     'dropped-custom-properties': 'Dropped custom properties',
     'dropped-experiment-metadata': 'Dropped experiment metadata',
     'dropped-maintainer': 'Dropped maintainer metadata',
-    'dropped-mobile-key-availability': 'Dropped mobile-key availability',
+    'dropped-mobile-key-now-server-only': 'Dropped mobile-key availability (now server-only)',
+    'dropped-mobile-key-still-visible': 'Dropped mobile-key availability (still client-visible)',
     'dropped-prerequisite': 'Dropped prerequisites',
     'dropped-private-attribute': 'Dropped private attributes',
+    'enabled-false-non-boolean': 'enabled=false on non-boolean features',
+    'identity-override-as-rule': 'Identity overrides converted to leading rules',
+    'identity-traits-referenced': 'Identity traits referenced by segment rules',
     'individual-target-as-rule': 'Individual targets converted to rules',
     'skipped-rule': 'Skipped rules (unsupported operators)',
     'unexportable-segment-membership': 'Unexportable segment membership',
 };
-const renderRebucketedRollouts = (notes) => {
+const SIGNAL_SPECS = {
+    'dropped-mobile-key-now-server-only': {
+        render: (count, keys) => `**${count} flag${count === 1 ? '' : 's'} ${count === 1 ? 'will' : 'will'} stop reaching mobile clients** ` +
+            `(${keys.map((k) => `\`${k}\``).join(', ')}). LaunchDarkly had \`usingMobileKey:true\` with ` +
+            `\`usingEnvironmentId:false\` — these were mobile-only and won't be visible to mobile SDKs post-migration. ` +
+            `Rebuild client-side access by hand before cutover.`,
+    },
+    'dropped-prerequisite': {
+        render: (count, keys) => `**${count} flag${count === 1 ? '' : 's'} lost cross-flag dependencies** (${keys.map((k) => `\`${k}\``).join(', ')}). ` +
+            `The Quonfig copy now serves its variations independently of its parent flag. ` +
+            `Review §'Dropped prerequisites' below.`,
+    },
+    'rebucketed-rollout': {
+        render: (count) => `**${count} flag${count === 1 ? '' : 's'} will re-bucket users.** Coordinate comms or drain affected ` +
+            `rollouts — see 'Users will be re-bucketed' below.`,
+    },
+    'skipped-rule': {
+        render: (count, keys) => `**${count} flag${count === 1 ? '' : 's'} had rules skipped** (${keys.map((k) => `\`${k}\``).join(', ')}) — ` +
+            `a clause used an unsupported operator. Rebuild the rule by hand before cutover.`,
+    },
+    'unexportable-segment-membership': {
+        render: (count, keys) => `**${count} segment${count === 1 ? '' : 's'} ${count === 1 ? 'has' : 'have'} missing membership** (${keys
+            .map((k) => `\`${k}\``)
+            .join(', ')}). Re-author or sync from your IdP before cutover.`,
+    },
+};
+const SIGNAL_ORDER = [
+    'dropped-mobile-key-now-server-only',
+    'dropped-prerequisite',
+    'rebucketed-rollout',
+    'unexportable-segment-membership',
+    'skipped-rule',
+];
+const MAX_EXAMPLE_KEYS = 3;
+const groupKeysByCategory = (notes) => {
+    const map = new Map();
+    for (const note of notes) {
+        const list = map.get(note.category) ?? [];
+        list.push(note.key);
+        map.set(note.category, list);
+    }
+    return map;
+};
+const renderBeforeYouCutOver = (notes) => {
+    if (!notes || notes.length === 0)
+        return null;
+    const byCategory = groupKeysByCategory(notes);
+    const items = [];
+    for (const category of SIGNAL_ORDER) {
+        const keys = byCategory.get(category);
+        if (!keys || keys.length === 0)
+            continue;
+        const sortedKeys = [...keys].sort((a, b) => a.localeCompare(b));
+        const example = sortedKeys.slice(0, MAX_EXAMPLE_KEYS);
+        const truncated = sortedKeys.length > MAX_EXAMPLE_KEYS ? [...example, '…'] : example;
+        items.push(SIGNAL_SPECS[category].render(sortedKeys.length, truncated));
+    }
+    if (items.length === 0)
+        return null;
+    const lines = [
+        '## Before you cut over',
+        '',
+        `${items.length} thing${items.length === 1 ? ' needs' : 's need'} a human decision before flipping the SDK:`,
+        '',
+    ];
+    items.forEach((item, idx) => {
+        lines.push(`${idx + 1}. ${item}`);
+    });
+    const ignoreParts = [];
+    const maintainerCount = byCategory.get('dropped-maintainer')?.length ?? 0;
+    if (maintainerCount > 0) {
+        ignoreParts.push(`dropped maintainer metadata (${maintainerCount} entries — git authorship replaces it)`);
+    }
+    const mobileKeyCount = byCategory.get('dropped-mobile-key-still-visible')?.length ?? 0;
+    if (mobileKeyCount > 0) {
+        ignoreParts.push(`dropped mobile-key availability (${mobileKeyCount} entries — all still client-visible via usingEnvironmentId)`);
+    }
+    if (ignoreParts.length > 0) {
+        lines.push('', `You can ignore: ${ignoreParts.join(', ')}.`);
+    }
+    return lines.join('\n');
+};
+const renderRebucketedRollouts = (notes, source) => {
     const rollouts = (notes ?? []).filter((n) => n.category === 'rebucketed-rollout');
     if (rollouts.length === 0)
         return null;
+    const sourceLabel = source === 'flagsmith' ? 'Flagsmith' : source === 'launchdarkly' ? 'LaunchDarkly' : source;
     const lines = [
         '## Users will be re-bucketed',
         '',
-        `**${rollouts.length}** flag(s)/segment(s) use a percentage rollout. LaunchDarkly and Quonfig hash buckets ` +
+        `**${rollouts.length}** flag(s)/segment(s) use a percentage rollout. ${sourceLabel} and Quonfig hash buckets ` +
             `differently, so which users land in which bucket *will change* after migration — the rollout percentage is ` +
             `preserved, but individual user assignments are not. Review these before cutover so the re-bucketing is not a surprise:`,
         '',
@@ -163,7 +285,77 @@ const renderRebucketedRollouts = (notes) => {
     }
     return lines.join('\n');
 };
-const renderConversionNotes = (notes) => {
+/**
+ * Categories that are pure informational noise (drowned out the signal in the
+ * 172-note LD migration report — see qfg-ve5w). Render as a 1-line rollup +
+ * collapsible `<details>` block instead of N top-level bullets.
+ */
+const COLLAPSED_CATEGORIES = {
+    'dropped-maintainer': (count) => `${count} flag${count === 1 ? '' : 's'} had a maintainer ID dropped. Intentional — Quonfig authorship lives in ` +
+        `git history. No action required.`,
+    'dropped-mobile-key-still-visible': (count) => `${count} flag${count === 1 ? '' : 's'} had \`usingMobileKey:true\` collapsed into the single \`sendToClientSdk\` ` +
+        `boolean. Each flag is still client-visible via \`usingEnvironmentId\`. No action required.`,
+};
+/**
+ * Render the `dropped-prerequisite` subsection (qfg-nb4n): one multi-line entry
+ * per child flag with nested parent bullets naming each variation index, plus
+ * a trailing inverted view that lists each orphaned parent and its downstream
+ * consumers. Returns the rendered lines (without the `### …` header — that is
+ * pushed by the caller so the section grouping stays consistent).
+ */
+const renderDroppedPrerequisiteBody = (notes) => {
+    const sorted = [...notes].sort((a, b) => a.key.localeCompare(b.key));
+    const lines = [];
+    // Forward view: child flag → parents.
+    for (const note of sorted) {
+        const edges = note.prerequisites;
+        if (!edges || edges.length === 0) {
+            // Backward-compat fallback when a future caller forgets the structured payload.
+            lines.push(`- \`${note.key}\` — ${note.detail}`);
+            continue;
+        }
+        lines.push(`- \`${note.key}\` evaluated independently of its ${edges.length} parent${edges.length === 1 ? '' : 's'}:`);
+        for (const edge of edges) {
+            lines.push(`  - was gated on \`${edge.parentKey}\` = variation ${edge.variation}`);
+        }
+        lines.push('  To preserve the gate, add a leading rule matching the same parent state, or wrap reads in app code.');
+    }
+    // Inverted view: parent → children that depended on it.
+    const parentToChildren = new Map();
+    for (const note of sorted) {
+        for (const edge of note.prerequisites ?? []) {
+            const set = parentToChildren.get(edge.parentKey) ?? new Set();
+            set.add(note.key);
+            parentToChildren.set(edge.parentKey, set);
+        }
+    }
+    if (parentToChildren.size > 0) {
+        lines.push('', '#### Orphaned parent flags (inverted view)', '');
+        const parents = [...parentToChildren.keys()].sort((a, b) => a.localeCompare(b));
+        for (const parent of parents) {
+            const children = [...(parentToChildren.get(parent) ?? [])].sort((a, b) => a.localeCompare(b));
+            const childList = children.map((c) => `\`${c}\``).join(', ');
+            lines.push(`- **\`${parent}\`** is now an orphaned dependency. Downstream flags that depended on it: ${childList}.`);
+        }
+    }
+    return lines;
+};
+/**
+ * qfg-l8uz: substitute every `<hex maintainerId>` in a dropped-maintainer
+ * detail with `<id> (<email>)` so the per-flag rollup reads as a human label
+ * instead of an opaque hex string. No-op when the map is empty/missing or the
+ * ID isn't in it (team-key drops, partial member visibility) — the unsubstituted
+ * line is still informative.
+ */
+const decorateMaintainerDetail = (detail, maintainerMap) => {
+    if (!maintainerMap)
+        return detail;
+    return detail.replaceAll(/[\da-f]{24}/g, (match) => {
+        const email = maintainerMap[match];
+        return email ? `${match} (${email})` : match;
+    });
+};
+const renderConversionNotes = (notes, maintainerMap) => {
     // `skipped-config` (own section) and `rebucketed-rollout` (own section) are
     // rendered elsewhere — everything else is grouped by category here.
     const grouped = (notes ?? []).filter((n) => n.category !== 'rebucketed-rollout' && n.category !== 'skipped-config');
@@ -182,12 +374,141 @@ const renderConversionNotes = (notes) => {
             continue;
         lines.push('', `### ${CONVERSION_NOTE_HEADINGS[category]}`, '');
         const sorted = [...forCategory].sort((a, b) => a.key.localeCompare(b.key));
+        const rollup = COLLAPSED_CATEGORIES[category];
+        if (rollup) {
+            lines.push(rollup(sorted.length), '', '<details><summary>Per-flag list</summary>', '');
+            for (const note of sorted) {
+                const detail = category === 'dropped-maintainer' ? decorateMaintainerDetail(note.detail, maintainerMap) : note.detail;
+                lines.push(`- \`${note.key}\` — ${detail}`);
+            }
+            lines.push('', '</details>');
+            continue;
+        }
+        if (category === 'dropped-prerequisite') {
+            lines.push(...renderDroppedPrerequisiteBody(sorted));
+            continue;
+        }
         for (const note of sorted) {
             lines.push(`- \`${note.key}\` — ${note.detail}`);
         }
     }
     return lines.join('\n');
 };
+/**
+ * Maps each lossy conversion-note category to a Follow-up checklist bucket plus
+ * a 1-line remediation hint. Categories not listed here (or `skipped-config` /
+ * housekeeping categories like `dropped-maintainer`) are intentionally not
+ * surfaced as checklist items — they get their own dedicated report sections
+ * or are pure-metadata losses that don't require human follow-up.
+ */
+const FOLLOW_UP_BUCKETS = {
+    'dropped-mobile-key-now-server-only': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — flag was mobile-only in LaunchDarkly (usingMobileKey:true, usingEnvironmentId:false) and will not reach mobile SDKs after migration; restore client-side access by hand.`,
+    },
+    'dropped-prerequisite': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — restore the dropped prerequisite gate manually; Quonfig v1 has no cross-flag dependency operator.`,
+    },
+    'individual-target-as-rule': {
+        bucket: 'reviewPostCutover',
+        hint: (key) => `\`${key}\` — individual user targets are now a leading rule; the LaunchDarkly targets pane affordance is gone.`,
+    },
+    'rebucketed-rollout': {
+        bucket: 'reviewPostCutover',
+        hint: (key) => `\`${key}\` — percentage rollout will re-bucket users post-migration; communicate before cutover.`,
+    },
+    'skipped-rule': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — a rule clause used an unsupported operator and was skipped; rebuild the rule by hand.`,
+    },
+    'unexportable-segment-membership': {
+        bucket: 'mustFixBeforeCutover',
+        hint: (key) => `\`${key}\` — segment shell migrated but membership is empty (LD big/synced segment); repopulate members before cutover.`,
+    },
+};
+/**
+ * Folds conversion notes into a followUp checklist. De-duplicates by hint
+ * string so a flag with two dropped prerequisites doesn't produce two
+ * identical checkbox lines.
+ */
+export const deriveFollowUpFromConversionNotes = (base, notes) => {
+    const mustFix = new Set(base.mustFixBeforeCutover);
+    const review = new Set(base.reviewPostCutover);
+    for (const note of notes ?? []) {
+        const mapping = FOLLOW_UP_BUCKETS[note.category];
+        if (!mapping)
+            continue;
+        const line = mapping.hint(note.key);
+        if (mapping.bucket === 'mustFixBeforeCutover')
+            mustFix.add(line);
+        else
+            review.add(line);
+    }
+    return { mustFixBeforeCutover: [...mustFix], reviewPostCutover: [...review] };
+};
+/**
+ * Static, content-stable appendix describing v1 behavioral gaps between
+ * LaunchDarkly and Quonfig (plan §5.4 / qfg-ox7m). Documentation, not data —
+ * does not vary across runs. Rendered only when source === 'launchdarkly'.
+ */
+const LAUNCHDARKLY_BEHAVIORAL_DIFFERENCES_APPENDIX = [
+    '## Behavioral differences post-cutover (independent of this import)',
+    '',
+    '- LaunchDarkly evaluates targets/contextTargets *before* rules. Quonfig has no',
+    '  individual-target primitive; user/context targets are now a leading PROP_IS_ONE_OF',
+    '  rule. Adding/removing individuals is now a config edit (qfg set / web UI), not a',
+    '  separate targeting UI pane.',
+    "- LaunchDarkly's 'off' toggle disappears. A flag is on iff at least one rule",
+    '  matches; there is no global kill-switch unless you author one as a top rule.',
+    '- offVariation does not exist in Quonfig. The off-state behavior of any flag',
+    '  that was on=false in LD has been baked into a single ALWAYS_TRUE rule serving',
+    '  that variation.',
+    '- Mobile SDK keys: LaunchDarkly distinguished mobile-key vs environment-id',
+    '  availability. Quonfig has one sendToClientSdk bool — your iOS/Android and',
+    '  browser-JS SDKs now share the same client-visibility setting.',
+    '- Maintainer is no longer a field on flags. `git log path/to/flag.json` is the',
+    '  new source of truth.',
+].join('\n');
+/**
+ * Flagsmith-specific behavioral-differences appendix (plan §5.5). Same shape
+ * as the LD version above — static documentation about gaps a customer reading
+ * MIGRATION_REPORT.md should know about independently of their specific data.
+ */
+const FLAGSMITH_BEHAVIORAL_DIFFERENCES_APPENDIX = [
+    '## Behavioral differences post-cutover (independent of this import)',
+    '',
+    '- `enabled=false` semantics differ. Flagsmith ignores `feature_state_value` when',
+    "  `enabled=false` and the SDK serves your code's hardcoded default. Quonfig always",
+    '  serves the configured value. For boolean features the migrator emits `false`; for',
+    '  non-boolean features it emits the stored `feature_state_value` and surfaces every',
+    '  affected flag under "Coerced sentinel rule values" above. Review each before',
+    '  cutover — Flagsmith\'s "off" behavior does NOT round-trip.',
+    '- Flagsmith has no individual-target primitive in Quonfig v1. Identity overrides',
+    '  are emitted as leading `PROP_IS_ONE_OF` rules on `user.key`. Adding/removing an',
+    '  identity is now a config edit (qfg set / web UI), not a per-identity row.',
+    '- Identity traits are runtime context Flagsmith infers from the trait directory.',
+    '  Quonfig has no server-side trait store — your SDK callers must send every trait',
+    '  attribute referenced by a segment rule on the eval context. See "Identity traits',
+    '  referenced by segment rules" above for the exhaustive list.',
+    '- Multivariate bucketing salts differ between Flagsmith and Quonfig. The percentage',
+    '  allocation is preserved, but identity → variation assignments WILL change. See',
+    '  "Users will be re-bucketed" above.',
+    '- MODULO and PERCENTAGE_SPLIT segment-condition operators have no Quonfig equivalent.',
+    '  Rules using them were dropped with `skipped-rule` notes; rebuild by hand if you',
+    '  need the segmentation.',
+    '- Segment rule combinators `type=ANY` and `type=NONE` (within-rule OR / NAND) have',
+    '  no Quonfig equivalent — Quonfig criteria within a single rule are AND-only. Those',
+    '  rules were dropped with `skipped-rule` notes.',
+    "- `:semver`-suffixed values are mapped to Quonfig's `PROP_SEMVER_*` operators.",
+    '  Inclusive variants (GTE/LTE) have no semver equivalent and were dropped.',
+    '- Soft-deleted features in Flagsmith are functionally hard-deleted from the public',
+    '  API (404 on GET, absent from list responses). The migrator cannot enumerate them;',
+    '  any features deleted before this snapshot was taken are simply not present in the',
+    '  Quonfig workspace.',
+    '- Feature owners, project metadata, change requests, and scheduled changes are out',
+    '  of v1 scope. None round-trip into Quonfig.',
+].join('\n');
 const renderFollowUp = (followUp) => {
     const must = followUp.mustFixBeforeCutover.length === 0
         ? NONE
@@ -212,7 +533,11 @@ export const buildMigrationReport = (data) => {
     if (data.dryRun) {
         sections.push('> **DRY RUN** — no files were written to the workspace during this run.');
     }
-    sections.push(`# Migration Report (from ${data.source})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`, renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap));
+    sections.push(`# Migration Report (from ${data.source})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`);
+    const beforeYouCutOver = renderBeforeYouCutOver(data.conversionNotes);
+    if (beforeYouCutOver !== null)
+        sections.push(beforeYouCutOver);
+    sections.push(renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap, data.maintainerMap));
     const dropped = renderDroppedOverrides(data.droppedOverrides);
     if (dropped !== null)
         sections.push(dropped);
@@ -222,16 +547,22 @@ export const buildMigrationReport = (data) => {
     const skipped = renderSkippedConfigs(data.skippedConfigs);
     if (skipped !== null)
         sections.push(skipped);
-    const coerced = renderCoercedSentinels(data.coercedSentinels);
+    const coerced = renderCoercedSentinels(data.coercedSentinels, data.source);
     if (coerced !== null)
         sections.push(coerced);
-    const rebucketed = renderRebucketedRollouts(data.conversionNotes);
+    const rebucketed = renderRebucketedRollouts(data.conversionNotes, data.source);
     if (rebucketed !== null)
         sections.push(rebucketed);
-    const conversionNotes = renderConversionNotes(data.conversionNotes);
+    const conversionNotes = renderConversionNotes(data.conversionNotes, data.maintainerMap);
     if (conversionNotes !== null)
         sections.push(conversionNotes);
     sections.push(renderFollowUp(data.followUp));
+    if (data.source === 'launchdarkly') {
+        sections.push(LAUNCHDARKLY_BEHAVIORAL_DIFFERENCES_APPENDIX);
+    }
+    if (data.source === 'flagsmith') {
+        sections.push(FLAGSMITH_BEHAVIORAL_DIFFERENCES_APPENDIX);
+    }
     return sections.join('\n\n') + '\n';
 };
 export const migrationReportPath = (outputDir) => path.join(outputDir, 'MIGRATION_REPORT.md');