@quonfig/cli 0.0.15 → 0.0.17

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.15 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.17 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -46,6 +46,7 @@ USAGE
 * [`qfg migrate status`](#qfg-migrate-status)
 * [`qfg override [NAME]`](#qfg-override-name)
 * [`qfg pull`](#qfg-pull)
+* [`qfg push`](#qfg-push)
 * [`qfg schema NAME`](#qfg-schema-name)
 * [`qfg sdk-key`](#qfg-sdk-key)
 * [`qfg sdk-key create`](#qfg-sdk-key-create)
@@ -88,7 +89,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.15/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/config-schema.ts)_
 
 ## `qfg create NAME`
 
@@ -160,7 +161,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.15/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/create.ts)_
 
 ## `qfg flag info [NAME]`
 
@@ -360,7 +361,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.15/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -383,7 +384,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -415,7 +416,7 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/get.ts)_
 
 ## `qfg info [NAME]`
 
@@ -463,7 +464,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.15/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -472,13 +473,15 @@ Initialize or update a Quonfig workspace
 ```
 USAGE
   $ qfg init [DIRECTORY] [--json] [--interactive] [--no-color] [--verbose] [--dry-run] [--samples]
+    [--workspace <value>]
 
 ARGUMENTS
   DIRECTORY  [default: .] Target directory (default: current directory)
 
 FLAGS
-  --dry-run       Show what would be done without writing anything
-  --[no-]samples  Include sample configs (default: yes on first init, no on update)
+  --dry-run            Show what would be done without writing anything
+  --[no-]samples       Include sample configs (default: yes on first init, no on update)
+  --workspace=<value>  Workspace slug to pin in quonfig.json (Guard 1). If omitted, no pin is written.
 
 GLOBAL FLAGS
   --[no-]interactive  Force interactive mode
@@ -501,7 +504,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -531,7 +534,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -571,7 +574,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/list.ts)_
 
 ## `qfg login`
 
@@ -596,7 +599,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -619,7 +622,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/logout.ts)_
 
 ## `qfg mcp`
 
@@ -652,7 +655,7 @@ EXAMPLES
   $ qfg mcp --url http://local-app.quonfig-staging.com:3003/api/v1/mcp
 ```
 
-_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/mcp.ts)_
+_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/mcp.ts)_
 
 ## `qfg migrate`
 
@@ -706,7 +709,7 @@ EXAMPLES
   $ qfg migrate --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-config --staging
 ```
 
-_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate.ts)_
 
 ## `qfg migrate doctor`
 
@@ -744,7 +747,7 @@ EXAMPLES
   $ qfg migrate doctor --json
 ```
 
-_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate/doctor.ts)_
 
 ## `qfg migrate my-code`
 
@@ -776,7 +779,7 @@ EXAMPLES
   $ qfg migrate my-code --dry-run
 ```
 
-_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate/my-code.ts)_
 
 ## `qfg migrate status`
 
@@ -807,7 +810,7 @@ EXAMPLES
   $ qfg migrate status --json
 ```
 
-_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate/status.ts)_
 
 ## `qfg override [NAME]`
 
@@ -851,7 +854,7 @@ EXAMPLES
   $ qfg override my.double.config --value=3.14159
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/override.ts)_
 
 ## `qfg pull`
 
@@ -895,7 +898,55 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/pull.ts)_
+
+## `qfg push`
+
+Push local config changes up to your workspace on Quonfig cloud.
+
+```
+USAGE
+  $ qfg push [--json] [--interactive] [--no-color] [--verbose] [--dir <value>] [--workspace <value>]
+    [--yes] [--skip-validate] [--no-pin-write] [-m <value>]
+
+FLAGS
+  -m, --message=<value>    Commit message for bare-path pushes (ignored on clone-path; push what is already committed)
+      --dir=<value>        Local directory to push (defaults to QUONFIG_DIR env var)
+      --no-pin-write       Do not offer to write workspace slug into quonfig.json on success
+      --skip-validate      Skip `qfg validate` preflight
+      --workspace=<value>  Workspace slug or UUID (defaults to active profile)
+      --yes                Skip the standard Y/N confirm. Never skips typed-slug prompts.
+
+GLOBAL FLAGS
+  --[no-]interactive  Force interactive mode
+  --json              Format output as json.
+  --no-color          Do not colorize output
+  --verbose           Verbose output
+
+DESCRIPTION
+  Push local config changes up to your workspace on Quonfig cloud.
+
+  Enforces three guards before touching the remote:
+  1. The dir's quonfig.json "workspace" pin must match the backend (if set).
+  2. The dir's git origin must match the backend repo URL (if set).
+  3. A diff summary is shown; destructive changes (10+ deletes, >=25% of
+  files, or an unpinned dir) require typing the workspace slug to confirm.
+
+  qfg push                                 # uses QUONFIG_DIR + profile workspace
+  qfg push --dir ./our-config
+  qfg push --dir ./our-config --workspace acme-prod
+  qfg push --dir ./our-config --yes        # skip normal Y/N (never skips typed-slug)
+  qfg push --dir ./our-config --skip-validate
+
+EXAMPLES
+  $ qfg push --dir ./our-config
+
+  $ qfg push --workspace acme-prod --dir ./our-config
+
+  $ qfg push --dir ./our-config --yes
+```
+
+_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/push.ts)_
 
 ## `qfg schema NAME`
 
@@ -933,7 +984,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.15/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/schema.ts)_
 
 ## `qfg sdk-key`
 
@@ -960,7 +1011,7 @@ EXAMPLES
   $ qfg sdk-key revoke <key-id>
 ```
 
-_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key.ts)_
 
 ## `qfg sdk-key create`
 
@@ -992,7 +1043,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.15/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key/create.ts)_
 
 ## `qfg sdk-key list`
 
@@ -1021,7 +1072,7 @@ EXAMPLES
   $ qfg sdk-key list --environment production
 ```
 
-_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key/list.ts)_
 
 ## `qfg sdk-key revoke KEYID`
 
@@ -1048,7 +1099,7 @@ 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.15/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key/revoke.ts)_
 
 ## `qfg set-default [NAME]`
 
@@ -1119,7 +1170,7 @@ EXAMPLES
   $ qfg pull && qfg config-schema
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/set-default.ts)_
 
 ## `qfg set-rollout [NAME]`
 
@@ -1196,7 +1247,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.15/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -1228,7 +1279,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sync.ts)_
 
 ## `qfg toggle [NAME]`
 
@@ -1330,7 +1381,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -1353,7 +1404,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -1376,7 +1427,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -1409,7 +1460,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.15/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/workspace/bootstrap.ts)_
 
 ## `qfg workspace switch [SLUG]`
 
@@ -1437,7 +1488,7 @@ EXAMPLES
   $ qfg workspace switch my-workspace-slug
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.15/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/workspace/switch.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/commands/init.d.ts

@@ -8,6 +8,7 @@ export default class Init extends BaseCommand {
     static flags: {
         'dry-run': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         samples: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     run(): Promise<object>;
 }

package/dist/commands/init.js

@@ -1,6 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import { BaseCommand } from '../index.js';
 import { executeInit, planInit } from '../init/init-workspace.js';
+import { writeWorkspaceSlug } from '../util/quonfig-json.js';
 export default class Init extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -25,6 +26,10 @@ export default class Init extends BaseCommand {
             allowNo: true,
             description: 'Include sample configs (default: yes on first init, no on update)',
         }),
+        workspace: Flags.string({
+            description: 'Workspace slug to pin in quonfig.json (Guard 1). If omitted, no pin is written.',
+            required: false,
+        }),
     };
     async run() {
         const { args, flags } = await this.parse(Init);
@@ -45,6 +50,9 @@ export default class Init extends BaseCommand {
                     this.log(`  + ${action.description}`);
                 }
             }
+            if (flags.workspace) {
+                this.log(`  + Pin quonfig.json to workspace "${flags.workspace}"`);
+            }
             if (skipActions.length > 0) {
                 this.log('\nSkipped:');
                 for (const action of skipActions) {
@@ -66,10 +74,20 @@ export default class Init extends BaseCommand {
         }
         // Execute for real
         executeInit(plan, dir);
+        // If the user passed --workspace, pin the slug in quonfig.json
+        // (Guard 1 in project/plans/cli-git-sync.md). We deliberately keep this
+        // non-interactive: flag → write, no flag → no write. Users who need the
+        // pin later can run `qfg pull` (backfills) or edit the file directly.
+        if (flags.workspace) {
+            await writeWorkspaceSlug(dir, flags.workspace);
+        }
         this.log(`${mode} workspace: ${dir === '.' ? process.cwd() : dir}\n`);
         for (const action of writeActions) {
             this.log(`  + ${action.description}`);
         }
+        if (flags.workspace) {
+            this.log(`  + Pin quonfig.json to workspace "${flags.workspace}"`);
+        }
         for (const action of skipActions) {
             this.log(`  - ${action.description}`);
         }

package/dist/commands/migrate.js

@@ -4,10 +4,10 @@ import path from 'node:path';
 import { BaseCommand } from '../index.js';
 import { CrossSourceError, assertSourceMatches, readImportState } from '../migrate/import-state.js';
 import { applyLocalMigration } from '../migrate/local-write.js';
-import { PushConflictError } from '../migrate/push-strategy.js';
+import { PushConflictError } from '../util/clone-and-stack-push.js';
 import { pushMigrationToCloud } from '../migrate/push-to-cloud.js';
 import { UnknownSourceError, getSource } from '../migrate/registry.js';
-import { NotYetImplementedError } from '../migrate/source.js';
+import { NotYetImplementedError, } from '../migrate/source.js';
 import { applyLaunchBaseUrl } from '../migrate/sources/launch/api.js';
 import { mintGiteaToken } from '../util/gitea-api.js';
 import { displayUrl } from '../util/git-ops.js';
@@ -104,6 +104,7 @@ export default class Migrate extends BaseCommand {
                 return this.err(error.message);
             throw error;
         }
+        let duplicateResolutionsForWarn = null;
         try {
             await source.validateAuth(flags['api-key']);
             const environments = await source.listEnvironments();
@@ -148,12 +149,14 @@ export default class Migrate extends BaseCommand {
                     const result = await pushMigrationToCloud({
                         changes: toProcess,
                         commitMessage: buildCommitMessage(flags.from, toProcess.length),
+                        environments,
                         importState,
                         localDir: dir,
                         remoteUrl: repoUrl,
                         reportData: buildReportData(flags.from, toProcess.length),
                         source,
                     });
+                    duplicateResolutionsForWarn = result.duplicateResolutions;
                     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.`);
@@ -188,6 +191,7 @@ export default class Migrate extends BaseCommand {
                 reportData: buildReportData(flags.from, toProcess.length),
                 source,
             });
+            duplicateResolutionsForWarn = localResult.duplicateResolutions;
             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.`);
@@ -203,6 +207,13 @@ export default class Migrate extends BaseCommand {
                 return this.err(error.message);
             throw error;
         }
+        finally {
+            // Surface source-level warnings even if apply/push threw (e.g.
+            // detectDuplicateKeys). The source accumulator holds the data regardless.
+            warnAboutDroppedOverrides(this, source.getDroppedOverrides?.() ?? null);
+            warnAboutSkippedConfigs(this, source.getSkippedConfigs?.() ?? null);
+            warnAboutDuplicateResolutions(this, duplicateResolutionsForWarn);
+        }
     }
     async resolvePushWorkspace(slugOrId) {
         const authConfig = await loadAuthConfig();
@@ -250,6 +261,41 @@ function buildReportData(source, count) {
         unsupportedFeatures: [],
     };
 }
+function warnAboutDroppedOverrides(cmd, dropped) {
+    if (!dropped || dropped.total === 0)
+        return;
+    const envIds = Object.keys(dropped.byEnv).sort();
+    cmd.warn(`Dropped ${dropped.total} override section(s) referencing ${envIds.length} env ID(s) not present in the source's env list (likely archived/deleted):`);
+    for (const envId of envIds) {
+        const perFlag = dropped.byEnv[envId];
+        const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
+        cmd.warn(`  env-${envId}: ${totalForEnv} dropped from ${Object.keys(perFlag).length} flag(s)`);
+        for (const flagPath of Object.keys(perFlag).sort()) {
+            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.`);
+}
+function warnAboutDuplicateResolutions(cmd, resolved) {
+    if (!resolved || resolved.total === 0)
+        return;
+    cmd.warn(`Resolved ${resolved.total} cross-type key collision(s) in the source data by keeping the config side and deleting the other type(s). Review each and clean up the source system so the collision stops recurring:`);
+    const sorted = [...resolved.entries].sort((a, b) => a.key.localeCompare(b.key));
+    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.');
+}
+function warnAboutSkippedConfigs(cmd, skipped) {
+    if (!skipped || skipped.total === 0)
+        return;
+    cmd.warn(`Skipped ${skipped.total} invalid config(s) from the source system — these were not written to the workspace. Fix each in the source system and re-run:`);
+    const sorted = [...skipped.entries].sort((a, b) => a.key.localeCompare(b.key));
+    for (const entry of sorted) {
+        cmd.warn(`  ${entry.key}: ${entry.reason}`);
+    }
+    cmd.warn('Full detail is also written to MIGRATION_REPORT.md.');
+}
 function resolveTargetDir(dirFlag, cwd) {
     if (dirFlag)
         return path.resolve(cwd, dirFlag);

package/dist/commands/pull.d.ts

@@ -8,8 +8,21 @@ export default class Pull 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>;
+    /**
+     * Local-only backfill of the `workspace` pin in `quonfig.json`.
+     *
+     * - Missing pin → write it from the token response's `workspaceSlug`.
+     * - Pin already set and matches → no-op.
+     * - Pin already set and disagrees → log a warning showing both values
+     *   and LEAVE IT ALONE. Overwriting someone's explicit pin is a Guard 2
+     *   concern, not a pull concern — the next `qfg push` is where the
+     *   identity-check dispatches a hard abort.
+     *
+     * This never throws — a broken `quonfig.json` shouldn't fail `qfg pull`.
+     */
+    private backfillWorkspacePin;
     private looksLike401;
     private maybeWriteQuonfigDir;
     private refreshAndGetUrl;
-    private resolveRepoUrl;
+    private resolveTokenEntry;
 }

package/dist/commands/pull.js

@@ -5,6 +5,7 @@ import { BaseCommand } from '../index.js';
 import { getActiveProfile, loadAuthConfig } from '../util/token-storage.js';
 import { loadGiteaToken, isGiteaTokenExpired, saveGiteaToken } from '../util/gitea-token-storage.js';
 import { mintAndStoreGiteaReadToken, mintGiteaToken } from '../util/gitea-api.js';
+import { readWorkspaceSlug, writeWorkspaceSlug } from '../util/quonfig-json.js';
 import { isGitRepo, getRemoteUrl, gitFetch, gitSetRemote, canFastForward, hasDivergedFromRemote, gitMergeFfOnly, gitClone, displayUrl, } from '../util/git-ops.js';
 export default class Pull extends BaseCommand {
     static description = `Clone or update a local copy of your workspace config files.
@@ -56,7 +57,8 @@ CLI shortcuts (no JSON editing needed for simple cases):
         }
         this.verboseLog('Pull', { workspaceId, dir: resolvedDir });
         // Get or mint Gitea read token
-        const repoUrl = await this.resolveRepoUrl(workspaceId);
+        const tokenEntry = await this.resolveTokenEntry(workspaceId);
+        const repoUrl = tokenEntry.repoUrl;
         // Perform git operation
         const isRepo = await isGitRepo(resolvedDir);
         if (isRepo) {
@@ -132,8 +134,61 @@ CLI shortcuts (no JSON editing needed for simple cases):
         }
         // Write QUONFIG_DIR to ~/.quonfig/config if not set
         await this.maybeWriteQuonfigDir(resolvedDir);
+        // Backfill the `workspace` pin in `quonfig.json` if missing
+        // (Guard 1 in project/plans/cli-git-sync.md). Local-only write — we
+        // intentionally do NOT commit or push here; the user's next `qfg push`
+        // will sweep it up naturally.
+        await this.backfillWorkspacePin(resolvedDir, tokenEntry, workspaceId);
         return { dir: resolvedDir, workspaceId };
     }
+    /**
+     * Local-only backfill of the `workspace` pin in `quonfig.json`.
+     *
+     * - Missing pin → write it from the token response's `workspaceSlug`.
+     * - Pin already set and matches → no-op.
+     * - Pin already set and disagrees → log a warning showing both values
+     *   and LEAVE IT ALONE. Overwriting someone's explicit pin is a Guard 2
+     *   concern, not a pull concern — the next `qfg push` is where the
+     *   identity-check dispatches a hard abort.
+     *
+     * This never throws — a broken `quonfig.json` shouldn't fail `qfg pull`.
+     */
+    async backfillWorkspacePin(dir, tokenEntry, workspaceId) {
+        let backendSlug = tokenEntry.workspaceSlug;
+        if (!backendSlug) {
+            // Older cached entries lack the slug. Mint a fresh one solely to learn the
+            // slug. Cheap (one API call), and the refresh updates the cache for next time.
+            try {
+                const fresh = await mintAndStoreGiteaReadToken(workspaceId);
+                backendSlug = fresh.workspaceSlug;
+            }
+            catch (error) {
+                this.verboseLog('Pull', `Could not mint token to learn workspace slug: ${String(error)}`);
+                return;
+            }
+        }
+        if (!backendSlug) {
+            this.verboseLog('Pull', 'Backend did not return a workspaceSlug; skipping pin backfill.');
+            return;
+        }
+        try {
+            const existingPin = await readWorkspaceSlug(dir);
+            if (!existingPin) {
+                await writeWorkspaceSlug(dir, backendSlug);
+                this.verboseLog('Pull', `Backfilled workspace pin "${backendSlug}" into quonfig.json.`);
+                return;
+            }
+            if (existingPin !== backendSlug) {
+                this.log('');
+                this.log(`Warning: quonfig.json pins workspace "${existingPin}", but the backend says this workspace is "${backendSlug}".`);
+                this.log('Leaving the existing pin in place. Run `qfg push` to see the full identity check.');
+            }
+        }
+        catch (error) {
+            // Non-fatal — pull itself already succeeded.
+            this.verboseLog('Pull', `Could not backfill workspace pin: ${String(error)}`);
+        }
+    }
     looksLike401(err) {
         const msg = err instanceof Error ? err.message : String(err);
         return msg.includes('401') || msg.toLowerCase().includes('authentication failed');
@@ -158,17 +213,22 @@ CLI shortcuts (no JSON editing needed for simple cases):
     }
     async refreshAndGetUrl(workspaceId) {
         const data = await mintGiteaToken(workspaceId, 'read', 'pull');
-        const entry = { token: data.token, repoUrl: data.repoUrl, expiresAt: data.expiresAt };
+        const entry = {
+            token: data.token,
+            repoUrl: data.repoUrl,
+            expiresAt: data.expiresAt,
+            workspaceSlug: data.workspaceSlug,
+        };
         await saveGiteaToken(workspaceId, entry);
         return entry.repoUrl;
     }
-    async resolveRepoUrl(workspaceId) {
+    async resolveTokenEntry(workspaceId) {
         let entry = await loadGiteaToken(workspaceId);
         if (!entry || isGiteaTokenExpired(entry)) {
             this.verboseLog('Pull', 'Minting new Gitea read token...');
             entry = await mintAndStoreGiteaReadToken(workspaceId);
         }
-        return entry.repoUrl;
+        return entry;
     }
 }
 /**