@quonfig/cli 0.0.52 → 0.0.54

package/README.md

@@ -17,7 +17,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.52 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.54 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -157,6 +157,7 @@ script doesn't need to know which env it's running in.
 * [`qfg sdk-key create`](#qfg-sdk-key-create)
 * [`qfg sdk-key list`](#qfg-sdk-key-list)
 * [`qfg sdk-key revoke KEYID`](#qfg-sdk-key-revoke-keyid)
+* [`qfg serve`](#qfg-serve)
 * [`qfg set-default [NAME]`](#qfg-set-default-name)
 * [`qfg set-rollout [NAME]`](#qfg-set-rollout-name)
 * [`qfg sync`](#qfg-sync)
@@ -195,7 +196,7 @@ EXAMPLES
   $ qfg activity restore my.flag --yes
 ```
 
-_See code: [src/commands/activity.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/activity.ts)_
+_See code: [src/commands/activity.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/activity.ts)_
 
 ## `qfg activity deleted`
 
@@ -224,7 +225,7 @@ EXAMPLES
   $ qfg activity deleted --json
 ```
 
-_See code: [src/commands/activity/deleted.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/activity/deleted.ts)_
+_See code: [src/commands/activity/deleted.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/activity/deleted.ts)_
 
 ## `qfg activity feed`
 
@@ -259,7 +260,7 @@ EXAMPLES
   $ qfg activity feed --json
 ```
 
-_See code: [src/commands/activity/feed.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/activity/feed.ts)_
+_See code: [src/commands/activity/feed.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/activity/feed.ts)_
 
 ## `qfg activity history [NAME]`
 
@@ -293,7 +294,7 @@ EXAMPLES
   $ qfg activity history request.timeout --json
 ```
 
-_See code: [src/commands/activity/history.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/activity/history.ts)_
+_See code: [src/commands/activity/history.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/activity/history.ts)_
 
 ## `qfg activity restore [NAME]`
 
@@ -332,7 +333,7 @@ EXAMPLES
   $ qfg activity restore request.timeout --type config --yes
 ```
 
-_See code: [src/commands/activity/restore.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/activity/restore.ts)_
+_See code: [src/commands/activity/restore.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/activity/restore.ts)_
 
 ## `qfg audit-log [NAME]`
 
@@ -360,7 +361,7 @@ EXAMPLES
   $ qfg audit-log my.flag
 ```
 
-_See code: [src/commands/audit-log.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/audit-log.ts)_
+_See code: [src/commands/audit-log.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/audit-log.ts)_
 
 ## `qfg config-schema`
 
@@ -389,7 +390,7 @@ EXAMPLES
   $ qfg config-schema --json-schema    # full JSON Schema document (copy into your editor)
 ```
 
-_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/config-schema.ts)_
 
 ## `qfg create NAME`
 
@@ -474,7 +475,7 @@ EXAMPLES
   $ qfg set-rollout my.new.flag --environment production --true-percent 20
 ```
 
-_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/create.ts)_
 
 ## `qfg delete NAME`
 
@@ -520,7 +521,7 @@ EXAMPLES
   $ qfg delete my.config --yes
 ```
 
-_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/delete.ts)_
+_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/delete.ts)_
 
 ## `qfg flag info [NAME]`
 
@@ -724,7 +725,7 @@ EXAMPLES
   $ qfg generate --targets node-ts -o ./dist # combine with targets
 ```
 
-_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -747,7 +748,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -779,7 +780,7 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/get.ts)_
 
 ## `qfg history NAME`
 
@@ -805,7 +806,7 @@ EXAMPLES
   $ qfg history my.flag
 ```
 
-_See code: [src/commands/history.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/history.ts)_
+_See code: [src/commands/history.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/history.ts)_
 
 ## `qfg info [NAME]`
 
@@ -853,7 +854,7 @@ EXAMPLES
   $ qfg info my.config.name --exclude-evaluations   # skip 24h stats
 ```
 
-_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -893,7 +894,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -923,7 +924,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -963,7 +964,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/list.ts)_
 
 ## `qfg log`
 
@@ -988,7 +989,7 @@ EXAMPLES
   $ qfg log --limit 5
 ```
 
-_See code: [src/commands/log.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/log.ts)_
+_See code: [src/commands/log.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/log.ts)_
 
 ## `qfg log-level NAME`
 
@@ -1053,7 +1054,7 @@ EXAMPLES
   $ qfg log-level log-level.my-app --target=Chatty --value=INFO --environment=production
 ```
 
-_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/log-level.ts)_
+_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/log-level.ts)_
 
 ## `qfg login`
 
@@ -1078,7 +1079,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -1101,7 +1102,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/logout.ts)_
 
 ## `qfg migrate`
 
@@ -1164,7 +1165,7 @@ EXAMPLES
   $ qfg migrate --from launch --source-api-key $LAUNCH_API_KEY --dir ./quonfig-repo --staging
 ```
 
-_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/migrate.ts)_
 
 ## `qfg migrate doctor`
 
@@ -1202,7 +1203,7 @@ EXAMPLES
   $ qfg migrate doctor --json
 ```
 
-_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/migrate/doctor.ts)_
 
 ## `qfg migrate my-code`
 
@@ -1234,7 +1235,7 @@ EXAMPLES
   $ qfg migrate my-code --dry-run
 ```
 
-_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/migrate/my-code.ts)_
 
 ## `qfg migrate status`
 
@@ -1265,7 +1266,7 @@ EXAMPLES
   $ qfg migrate status --json
 ```
 
-_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/migrate/status.ts)_
 
 ## `qfg override [NAME] [VALUE]`
 
@@ -1320,7 +1321,7 @@ EXAMPLES
   $ qfg override my.flag true --env=staging
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/override.ts)_
 
 ## `qfg pull`
 
@@ -1368,7 +1369,7 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/pull.ts)_
 
 ## `qfg push`
 
@@ -1417,7 +1418,7 @@ EXAMPLES
   $ qfg push --dir ./our-config --yes
 ```
 
-_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/push.ts)_
+_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/push.ts)_
 
 ## `qfg run [COMMAND]`
 
@@ -1468,7 +1469,7 @@ EXAMPLES
   $ qfg run --env DATABASE_URL=db.url --preserve-env --environment=staging -- npm test
 ```
 
-_See code: [src/commands/run.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/run.ts)_
+_See code: [src/commands/run.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/run.ts)_
 
 ## `qfg schema NAME`
 
@@ -1506,7 +1507,7 @@ EXAMPLES
   $ qfg schema my-schema --set-json-schema=@schemas/my-schema.json --protected
 ```
 
-_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/schema.ts)_
 
 ## `qfg sdk-key`
 
@@ -1533,7 +1534,7 @@ EXAMPLES
   $ qfg sdk-key revoke <key-id>
 ```
 
-_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/sdk-key.ts)_
 
 ## `qfg sdk-key create`
 
@@ -1565,7 +1566,7 @@ EXAMPLES
   $ qfg sdk-key create --environment staging --type browser
 ```
 
-_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/sdk-key/create.ts)_
 
 ## `qfg sdk-key list`
 
@@ -1594,7 +1595,7 @@ EXAMPLES
   $ qfg sdk-key list --environment production
 ```
 
-_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/sdk-key/list.ts)_
 
 ## `qfg sdk-key revoke KEYID`
 
@@ -1621,7 +1622,64 @@ EXAMPLES
   $ qfg sdk-key revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
 ```
 
-_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/sdk-key/revoke.ts)_
+
+## `qfg serve`
+
+Serve a local datadir over HTTP to browser/RN SDKs.
+
+```
+USAGE
+  $ qfg serve [--json] [--interactive] [--no-color] [--verbose] [--datadir <value>] [--environment <value>]
+    [--port <value>] [--host <value>] [--frontend-sdk-key <value>] [--cors-origin <value>...] [--watch]
+    [--allow-non-loopback]
+
+FLAGS
+  --allow-non-loopback        Confirm a LAN-reachable bind. Required when --host is not loopback.
+  --cors-origin=<value>...    [default: *] Allowed CORS origin (repeatable). Default is *; required when binding to a
+                              non-loopback host.
+  --datadir=<value>           Datadir to serve (defaults to ./our-config, then ./.quonfig, then errors). Honors
+                              QUONFIG_DIR.
+  --environment=<value>       [default: development] Which environment slug to evaluate. Honors QUONFIG_ENVIRONMENT.
+  --frontend-sdk-key=<value>  If set, every request must present Authorization: Basic 1:<key>. If unset, the server is
+                              open (matches the "datadir is the source of truth" mental model).
+  --host=<value>              [default: 127.0.0.1] Bind address. Loopback by default; non-loopback requires
+                              --allow-non-loopback.
+  --port=<value>              [default: 6580] TCP port to listen on. Errors on collision; pass --port <n> to retry.
+  --[no-]watch                Reload the envelope when the datadir changes. --no-watch disables.
+
+GLOBAL FLAGS
+  --[no-]interactive  Force interactive mode
+  --json              Format output as json.
+  --no-color          Do not colorize output
+  --verbose           Verbose output
+
+DESCRIPTION
+  Serve a local datadir over HTTP to browser/RN SDKs.
+
+  Reads configs from a local datadir and exposes them at
+  `GET /api/v2/configs/eval-with-context/{base64url(ctx)}`. Point your
+  browser SDK at the resulting URL (`http://localhost:6580` by default)
+  and the same client code that talks to api-delivery in production will
+  work unmodified.
+
+  Telemetry is intentionally not served — qfg serve has no Quonfig backend
+  behind it. Disable client-side telemetry with
+  `collectEvaluationSummaries: false` (and `contextUploadMode: "none"`),
+  or point the SDK's `telemetryUrl` at a real endpoint.
+
+  The server is bound to 127.0.0.1 by default; pass --allow-non-loopback
+  to confirm a LAN-reachable bind.
+
+EXAMPLES
+  $ qfg serve
+
+  $ qfg serve --datadir ./our-config --environment production
+
+  $ qfg serve --port 6581 --frontend-sdk-key PUBLIC_KEY
+```
+
+_See code: [src/commands/serve.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/serve.ts)_
 
 ## `qfg set-default [NAME]`
 
@@ -1692,7 +1750,7 @@ EXAMPLES
   $ qfg pull && qfg config-schema
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/set-default.ts)_
 
 ## `qfg set-rollout [NAME]`
 
@@ -1769,7 +1827,7 @@ EXAMPLES
   $ qfg set-rollout my.variant.flag --environment production --weights "a:33,b:33,c:34" --hash-by user.id
 ```
 
-_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -1801,7 +1859,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/sync.ts)_
 
 ## `qfg toggle [NAME]`
 
@@ -1903,7 +1961,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -1926,7 +1984,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -1949,7 +2007,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -1982,7 +2040,7 @@ EXAMPLES
   $ qfg workspace bootstrap --dir ./our-config --skip-validate
 ```
 
-_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/workspace/bootstrap.ts)_
 
 ## `qfg workspace create SLUG`
 
@@ -2016,7 +2074,7 @@ EXAMPLES
   $ qfg workspace create my-team --org 11111111-1111-1111-1111-111111111111
 ```
 
-_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/workspace/create.ts)_
+_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/workspace/create.ts)_
 
 ## `qfg workspace switch [SLUG]`
 
@@ -2044,7 +2102,7 @@ EXAMPLES
   $ qfg workspace switch acme/production
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.52/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.54/src/commands/workspace/switch.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/commands/migrate.d.ts

@@ -19,5 +19,11 @@ export default class Migrate extends BaseCommand {
         workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     run(): Promise<JsonObj | void>;
+    /**
+     * After a local (non-push) migration commits, the user is left at a prompt
+     * with a fresh directory and no obvious next move. Spell out the review →
+     * push flow explicitly.
+     */
+    private printLocalNextSteps;
     private resolvePushWorkspace;
 }

package/dist/commands/migrate.js

@@ -5,6 +5,7 @@ import { BaseCommand } from '../index.js';
 import { CrossSourceError, assertSourceMatches, readImportState } from '../migrate/import-state.js';
 import { applyLocalMigration, MigratorKeyCollisionError } from '../migrate/local-write.js';
 import { buildPushConflictSuggestion } from '../migrate/migrate-suggestion.js';
+import { migrationReportPath } from '../migrate/migration-report.js';
 import { PushConflictError, PushHookRejectedError } from '../util/clone-and-stack-push.js';
 import { MigratorVerifyError, pushMigrationToCloud } from '../migrate/push-to-cloud.js';
 import { UnknownSourceError, getSource } from '../migrate/registry.js';
@@ -20,6 +21,10 @@ import { displayUrl } from '../util/git-ops.js';
 import { resolveWorkspaceUuid } from '../util/resolve-workspace.js';
 import { loadAuthConfig } from '../util/token-storage.js';
 const DEFAULT_DIR = 'quonfig-repo';
+// How many fetched changes between progress lines during the (silent,
+// paginated) change-history fetch. Large accounts page through thousands of
+// changes 50 at a time; without periodic output the CLI looks frozen.
+const FETCH_PROGRESS_INTERVAL = 1000;
 export default class Migrate extends BaseCommand {
     static description = 'Migrate flags and configs from a legacy feature-flag system into a Quonfig workspace.\n\n' +
         'Currently supported sources:\n' +
@@ -172,9 +177,28 @@ export default class Migrate extends BaseCommand {
                 return this.err(error.message);
             throw error;
         }
+        // The fetch and write phases below are silent for a long time on a large
+        // account. Print a plan up front and a step line before each slow phase so
+        // the CLI never looks frozen, even without --verbose.
+        this.log(`Migrating from ${flags.from} into ${dir}.`);
+        if (flags['dry-run']) {
+            this.log('Mode: dry run — changes are summarized but nothing is written.');
+        }
+        else if (flags.push) {
+            this.log('Mode: migrate to a local dir, then push to the Quonfig cloud workspace.');
+        }
+        else {
+            this.log('Mode: local migration only — re-run with --push to also publish to a cloud workspace.');
+        }
+        this.log('');
         let duplicateResolutionsForWarn = null;
+        // Set to the target dir once a local (non-push) migration commits, so the
+        // `finally` block can print "what now?" guidance after the warnings.
+        let localNextStepsDir = null;
         try {
+            this.log(`Authenticating with ${flags.from}...`);
             await source.validateAuth(sourceApiKey);
+            this.log(`Reading the environment list from ${flags.from}...`);
             const environments = await source.listEnvironments();
             // Plan §4.1.1: tell the user the real history horizon BEFORE the slow
             // Phase-2 walk starts. validateAuth populated this for LD under
@@ -187,8 +211,15 @@ export default class Migrate extends BaseCommand {
             }
             const existing = readImportState(dir);
             const sinceEpochMs = computeSince(flags, existing);
+            this.log(`Fetching change history from ${flags.from} — this can take a few minutes for a large account...`);
             const changes = [];
-            for await (const change of source.fetchChanges(sinceEpochMs)) {
+            let lastReportedFetch = 0;
+            for await (const change of source.fetchChanges(sinceEpochMs, (fetched) => {
+                if (fetched - lastReportedFetch >= FETCH_PROGRESS_INTERVAL) {
+                    lastReportedFetch = fetched;
+                    this.log(`  ...fetched ${fetched} change(s) so far`);
+                }
+            })) {
                 changes.push(change);
             }
             const toProcess = flags.recent === undefined ? changes : changes.slice(-flags.recent);
@@ -239,6 +270,8 @@ export default class Migrate extends BaseCommand {
                     this.log(result.committed
                         ? `Pushed ${toProcess.length} change(s). commit=${result.commitSha?.slice(0, 8) ?? ''} action=${result.action}`
                         : `No net changes produced by this run. Nothing to commit or push.`);
+                    this.log(`Migration report written to ${migrationReportPath(dir)} — review it before cutover ` +
+                        '(it lives in the hidden .qf/ directory).');
                     return {
                         ...payload,
                         action: result.action,
@@ -285,6 +318,10 @@ export default class Migrate extends BaseCommand {
             this.log(localResult.committed
                 ? `Committed ${toProcess.length} change(s). commit=${localResult.commitSha?.slice(0, 8) ?? ''} action=${localResult.action}`
                 : `No net changes produced by this run. Nothing to commit.`);
+            // Print "what now?" guidance from the `finally` block (after the
+            // warnings) so it is the last thing the user sees.
+            if (localResult.committed)
+                localNextStepsDir = dir;
             return {
                 ...payload,
                 action: localResult.action,
@@ -307,8 +344,33 @@ export default class Migrate extends BaseCommand {
             warnAboutCoercedSentinels(this, source.getCoercedSentinels?.() ?? null);
             warnAboutDuplicateResolutions(this, duplicateResolutionsForWarn);
             warnAboutConversionNotes(this, source.getConversionNotes?.() ?? null);
+            if (localNextStepsDir)
+                this.printLocalNextSteps(localNextStepsDir);
         }
     }
+    /**
+     * After a local (non-push) migration commits, the user is left at a prompt
+     * with a fresh directory and no obvious next move. Spell out the review →
+     * push flow explicitly.
+     */
+    printLocalNextSteps(dir) {
+        this.log('');
+        this.log('Migration written to a local directory — nothing has been pushed to Quonfig cloud yet.');
+        this.log('');
+        this.log('Next steps:');
+        this.log(`  1. Review the migrated config files in ${dir}`);
+        this.log('  2. Read the migration report — it lists every config that was skipped,');
+        this.log('     coerced, or needs a manual follow-up:');
+        this.log(`       ${migrationReportPath(dir)}`);
+        this.log('     (it lives in the hidden .qf/ directory — use `ls -a` to see it)');
+        this.log('  3. Publish to a Quonfig workspace once the migration looks right:');
+        this.log(`       qfg push --dir ${dir} --workspace <org-slug>/<workspace-slug>`);
+        this.log('     (run `qfg login` first if you have not). You can also re-run this command');
+        this.log('     with `--push --workspace <org-slug>/<workspace-slug>` to migrate and push');
+        this.log('     in one step.');
+        this.log('');
+        this.log('Re-running `qfg migrate` later picks up only the changes made since this run.');
+    }
     async resolvePushWorkspace(slugOrId) {
         const authConfig = await loadAuthConfig();
         if (!authConfig)
@@ -368,7 +430,7 @@ function warnAboutDroppedOverrides(cmd, dropped) {
             cmd.warn(`    - ${flagPath} (${perFlag[flagPath]})`);
         }
     }
-    cmd.warn(`If any of these envs are still in use, restore them in the source system and re-run the migration. Full detail is also written to MIGRATION_REPORT.md.`);
+    cmd.warn(`If any of these envs are still in use, restore them in the source system and re-run the migration. Full detail is also written to .qf/MIGRATION_REPORT.md.`);
 }
 function warnAboutDuplicateResolutions(cmd, resolved) {
     if (!resolved || resolved.total === 0)
@@ -378,7 +440,7 @@ function warnAboutDuplicateResolutions(cmd, resolved) {
     for (const entry of sorted) {
         cmd.warn(`  ${entry.key} (${entry.collisionTypes.join(', ')}): kept ${entry.kept}, deleted ${entry.deleted.join(', ')}`);
     }
-    cmd.warn('Full detail is also written to MIGRATION_REPORT.md.');
+    cmd.warn('Full detail is also written to .qf/MIGRATION_REPORT.md.');
 }
 function warnAboutCoercedSentinels(cmd, coerced) {
     if (!coerced || coerced.total === 0)
@@ -393,7 +455,7 @@ function warnAboutCoercedSentinels(cmd, coerced) {
             cmd.warn(`    - ${flagPath} (${perFlag[flagPath]})`);
         }
     }
-    cmd.warn(`If you want a real default for these rules, set one in the source system and re-run the migration. Full detail is also written to MIGRATION_REPORT.md.`);
+    cmd.warn(`If you want a real default for these rules, set one in the source system and re-run the migration. Full detail is also written to .qf/MIGRATION_REPORT.md.`);
 }
 function warnAboutConversionNotes(cmd, notes) {
     if (!notes || notes.length === 0)
@@ -402,12 +464,12 @@ function warnAboutConversionNotes(cmd, notes) {
     if (rebucketed.length > 0) {
         cmd.warn(`${rebucketed.length} flag(s)/segment(s) use a percentage rollout — LaunchDarkly and Quonfig bucket users ` +
             `differently, so individual user assignments WILL change after migration (the rollout percentage is preserved). ` +
-            `See the "Users will be re-bucketed" section of MIGRATION_REPORT.md.`);
+            `See the "Users will be re-bucketed" section of .qf/MIGRATION_REPORT.md.`);
     }
     const other = notes.filter((n) => n.category !== 'rebucketed-rollout' && n.category !== 'skipped-config');
     if (other.length > 0) {
         cmd.warn(`${other.length} source concept(s) could not be converted exactly (dropped prerequisites, lossy individual ` +
-            `targets, etc.). Nothing was silently dropped — see the "Conversion notes" section of MIGRATION_REPORT.md.`);
+            `targets, etc.). Nothing was silently dropped — see the "Conversion notes" section of .qf/MIGRATION_REPORT.md.`);
     }
 }
 function warnAboutSkippedConfigs(cmd, skipped) {
@@ -418,7 +480,7 @@ function warnAboutSkippedConfigs(cmd, skipped) {
     for (const entry of sorted) {
         cmd.warn(`  ${entry.key}: ${entry.reason}`);
     }
-    cmd.warn('Full detail is also written to MIGRATION_REPORT.md.');
+    cmd.warn('Full detail is also written to .qf/MIGRATION_REPORT.md.');
 }
 function resolveTargetDir(dirFlag, cwd) {
     if (dirFlag)

package/dist/commands/push.js

@@ -238,9 +238,15 @@ export function buildRealDeps(cmd, orgSlug) {
             }
         },
         async getOriginMainSha(dir) {
-            // qfg-gj3i: clone-path returns the local origin/main SHA after
-            // fetch. Bare path has no `.git/` to rev-parse — return undefined
-            // and let the server apply its bare-path lock policy.
+            // Bare path: `diffHeadVsOrigin` (always called first by runPush)
+            // populated the probe clone. Its HEAD is our view of the workspace
+            // tip — and is exactly what the diff was computed against — so it is
+            // the correct `expectedSha` for the server-side optimistic lock
+            // (qfg-gj3i bare-path follow-up, qfg-nhcb). Without it the bare-path
+            // push omits expectedSha and the server rejects it with a 426.
+            if (barePathProbe)
+                return barePathProbe.remoteHeadSha;
+            // Clone path: the local origin/main SHA after fetch.
             if (!(await isGitRepo(dir)))
                 return;
             return getOriginMainSha(dir);

package/dist/commands/run.js

@@ -241,7 +241,6 @@ The flag separator '--' is REQUIRED between qfg flags and the child command.`;
         const quonfig = new Quonfig({
             sdkKey,
             collectEvaluationSummaries: false,
-            collectLoggerCounts: false,
             contextUploadMode: 'none',
             enableSSE: false,
             apiUrls: [getDeliveryUrl()],