@quonfig/cli 0.0.14 → 0.0.16

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.14 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.16 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)
@@ -59,7 +60,7 @@ USAGE
 * [`qfg whoami`](#qfg-whoami)
 * [`qfg workspace`](#qfg-workspace)
 * [`qfg workspace bootstrap`](#qfg-workspace-bootstrap)
-* [`qfg workspace switch`](#qfg-workspace-switch)
+* [`qfg workspace switch [SLUG]`](#qfg-workspace-switch-slug)
 
 ## `qfg config-schema`
 
@@ -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.14/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/mcp.ts)_
+_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.16/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.14/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.16/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.14/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -1409,15 +1460,18 @@ EXAMPLES
   $ qfg workspace bootstrap --dir ./our-config --skip-validate
 ```
 
-_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.14/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/workspace/bootstrap.ts)_
 
-## `qfg workspace switch`
+## `qfg workspace switch [SLUG]`
 
 Switch to a different workspace
 
 ```
 USAGE
-  $ qfg workspace switch [--json] [--interactive] [--no-color] [--verbose]
+  $ qfg workspace switch [SLUG] [--json] [--interactive] [--no-color] [--verbose]
+
+ARGUMENTS
+  SLUG  Workspace slug (or UUID) to switch to. Omit for an interactive picker.
 
 GLOBAL FLAGS
   --[no-]interactive  Force interactive mode
@@ -1430,9 +1484,11 @@ DESCRIPTION
 
 EXAMPLES
   $ qfg workspace switch
+
+  $ qfg workspace switch my-workspace-slug
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.14/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.16/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,7 +4,7 @@ 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';

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;
     }
 }
 /**

package/dist/commands/push.d.ts

@@ -0,0 +1,53 @@
+import type { JsonObj } from '../result.js';
+import { BaseCommand } from '../index.js';
+import { GiteaTokenResponse } from '../util/gitea-api.js';
+import type { GiteaTokenMintResult } from '../push/run-push.js';
+import { runPush } from '../push/run-push.js';
+export default class Push extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        dir: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        workspace: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'skip-validate': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'no-pin-write': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        message: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+    };
+    run(): Promise<JsonObj | void>;
+}
+/**
+ * Map a raw `gitea.token` API response into the `GiteaTokenMintResult` shape
+ * the push core (`runPush`) consumes. Kept as a pure function so we can unit
+ * test the wiring without a network — specifically, to regression-test that
+ * `workspaceId` on the result is the UUID the server returned, not the slug.
+ *
+ * The bug this guards against: before the backend started returning
+ * `workspaceId`, this module used `resp.workspaceSlug` as the `workspaceId`
+ * field, which caused `checkIdentity` to fail when the user passed
+ * `--workspace <UUID>` (requested=UUID, backend.workspaceId=slug → mismatch).
+ */
+export declare function giteaResponseToMintResult(resp: GiteaTokenResponse): GiteaTokenMintResult;
+/**
+ * Wire the real implementations of every dependency runPush needs. Kept in
+ * the command file so the pure core stays free of oclif / git shell imports.
+ *
+ * Returns a `{deps, cleanup}` pair. The caller MUST call `cleanup()` in a
+ * finally block so the bare-path probe clone is removed even on errors.
+ */
+export declare function buildRealDeps(cmd: Push): {
+    deps: Parameters<typeof runPush>[1];
+    cleanup: () => Promise<void>;
+};
+/**
+ * Copy the contents of `sourceDir` into `destDir`, skipping `.git/` and any
+ * temp push-clone scratch directories. Used as the `applyDelta` callback for
+ * bare-path pushes — we mirror local files into a fresh clone so that
+ * `cloneAndStackPush`'s `git add --all` + diff will reflect the union of
+ * (deletes, modifies, adds) we intend.
+ *
+ * IMPORTANT: this deletes files in destDir that are not in sourceDir so that
+ * deletions make it into the push. Without this the clone-and-stack produces
+ * an "adds-only" delta and destructive heuristics would never fire in the UI.
+ */
+export declare function copyDirMirror(sourceDir: string, destDir: string): Promise<void>;