@backifydev/cli 0.3.2 → 0.3.3

package/README.md

@@ -9,12 +9,13 @@ npx @backifydev/cli sync
 npx @backifydev/cli login
 npx @backifydev/cli status
 npx @backifydev/cli report --check
+npx @backifydev/cli pull
 npx @backifydev/cli ship
 ```
 
 `login` opens the Backify portal in your browser. Sign in and select an organization; the portal returns the organization and access token to the CLI through a random, short-lived callback bound to `127.0.0.1`. The CLI stores them in `~/.backify.json`. Set `portalUrl` in that file to use another portal, or `BACKIFY_PORTAL_URL` in the environment. `login <token> [organizationId]` remains available for scripted development.
-
-`init` installs `@backifydev/sdk`, writes `backify.json`, and maintains the Backify blocks in `AGENTS.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`. It preserves other instructions in those files.
+
+`init` installs `@backifydev/sdk`, writes `backify.json` and `BACKIFY.md`, and maintains only the selected coding tool's Backify block. Use `--agent codex` (`AGENTS.md`), `--agent claude` (`CLAUDE.md`), `--agent copilot` (`.github/copilot-instructions.md`), or `--agent gemini` (`GEMINI.md`). The CLI remembers the selection for `init`, `sync`, and `doctor`; new projects default to Codex. For any other tool, pass `--instruction-file <relative-path>` to use its native instruction or rule file, including nested paths; this is remembered too. It preserves other instructions and does not create or modify other tools' files.
 
 The app configuration stores `instructionVersion`, matching the version declared in each managed block and its immutable guide at `https://agent.backify.dev/v<number>`. The agent root always serves the latest guide as plain text. `doctor` detects version/content drift and malformed markers. Use `npx @backifydev/cli@latest sync` to explicitly upgrade all blocks and the configuration together; unrelated configuration and unmanaged instructions remain unchanged.
 
@@ -22,10 +23,12 @@ You can start from an empty folder without a Git repository. `init` creates a mi
 
 See the [agent setup guide](https://agent.backify.dev/).
 
-Copy the application AI prompt in Backify to receive an application-scoped, single-use pairing command. Codes expire after 15 minutes; redeemed sessions expire after seven days. Add `--clone` to the connection command only in an empty directory. Credentials are stored in the user's home configuration, not the project. The default API is `https://api.backify.dev/api`; local development can override it with `BACKIFY_API_URL` or the copied command's `--api` option. HTTPS is required outside loopback.
+Copy the application AI prompt in Backify to receive the application ID, organization ID, and an application-scoped, single-use pairing code; the agent guide supplies the connection and initialization commands. Codes expire after 15 minutes; redeemed sessions expire after seven days. Add `--clone` even when the current folder contains AI coding-tool scaffolding. Empty directories of any name are allowed. Hidden tool-metadata directories and files, Markdown instruction files, and default `work/` and `outputs/` directories may contain tool settings or artifacts. The CLI clones into a temporary directory, validates collisions, then merges without deleting or overwriting existing tool files. Existing Git metadata, root application source, and symlinked tool directories are rejected; file conflicts stop before repository files are installed. Credentials are stored in the user's home configuration, not the project. The default API is `https://api.backify.dev/api`; local development can override it with `BACKIFY_API_URL` or the connection command's `--api` option. HTTPS is required outside loopback.
 
 `init` adds a persistent delivery guide linked from the existing agent instructions. Before each application-building request, the agent sends only the user's own text through stdin to `backify prompt record --stdin --id <UUID>`, optionally adding repeated `--filename <basename>` arguments. Reuse the UUID on retries. The command never reads attachments; their bodies, extracted text, full paths, setup/pairing prompts, and credentials must not be submitted. History is displayed oldest-first under the application. This is an explicit agent workflow, not an automatic interceptor for every coding tool.
 
+`pull` checks the connected application, repository, branch, and repository root, then fetches GitHub using a short-lived scoped credential. It fast-forwards only a clean, non-diverged branch. Incoming updates blocked by local changes, untracked files, or diverged history return a blocked result and a nonzero exit code; nothing is stashed, reset, rebased, or force-pushed. Connecting an existing repository runs this update automatically, and the agent guide requires it before editing each new user request. It is not a background watcher.
+
 `ship` runs configured checks, verifies the repository/branch, and pushes already-committed source using a short-lived repository-scoped GitHub App credential. It never stages, commits, force-pushes, or fabricates preview testing. It waits for the exact healthy preview, then publishes when policy and permissions allow. Required testing/approval returns a pending state and preview URL, not a false successful production deployment. Use `--preview-only` to stop at preview, or `--timeout <seconds>` to change the default 1200-second wait. Applications must currently be at the repository root; Backify Cloud needs static index.html output, and customer Azure needs a Dockerfile serving port 8080.
 
 `disconnect` revokes that user's application CLI sessions. `logout` removes local credentials only. Prompt histories and local reports remain subject to application permissions. Deploy the matching API and publish CLI 0.3.0 before enabling this flow in production.

package/dist/index.js

@@ -769,35 +769,43 @@ async function packageFunctions(entry, output) {
 }
 
 // src/development.ts
-import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync4, renameSync, rmSync } from "node:fs";
-import { join as join3, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync as readdirSync2, writeFileSync as writeFileSync4, renameSync, rmSync, mkdtempSync, lstatSync as lstatSync2, cpSync } from "node:fs";
+import { dirname as dirname4, join as join3, resolve as resolve3 } from "node:path";
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 
 // src/setup.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readdirSync } from "node:fs";
-import { basename, dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2, readdirSync, lstatSync } from "node:fs";
+import { basename, dirname as dirname3, join as join2, resolve as resolve2, isAbsolute } from "node:path";
 import { spawnSync } from "node:child_process";
 
 // ../platform/dist/delivery.js
 var deliveryInstructions = `# Backify application delivery and prompt history
 
-Instruction version: 3
-Versioned guide: https://agent.backify.dev/v3/delivery.md
+Instruction version: 4
+Versioned guide: https://agent.backify.dev/v4/delivery.md
 
 These instructions are for AI coding tools building applications on Backify, not the Backify platform implementation. Complete the application and deliver a verified deployment, not just SDK setup. Respect the coding tool's own permissions and confirmation settings; preserve unrelated work and applicable repository instructions.
 
 ## Connect and initialize
 
-Use the connection command from the copied Backify prompt. The application ID, organization, API address, and single-use pairing code are already supplied there; never invent them. Pairing expires after 15 minutes. Never record the code or setup prompt in project files, Git, prompt history, or logs. The CLI stores an application-scoped session outside the repository. If access expires, obtain a new setup prompt or use CLI browser login.
+The copied Backify prompt supplies App Id, Organization, and, when available, Pair, plus this guide reference and a privacy warning. Substitute those values for <app-id>, <organization-id>, and <pairing-code> below; never invent them. Use npx @backifydev/cli@latest so tool-specific setup and metadata-preserving cloning are available. The public API URL is https://api.backify.dev/api. For a nonproduction environment, replace the --api value with an explicitly trusted endpoint, or omit --api when using a trusted BACKIFY_API_URL override; never send a pairing code to an unverified endpoint.
 
-Inspect the workspace before connecting. In an empty project folder, add --clone to the supplied connect command to clone the connected repository without a separate GitHub login. In an existing repository, verify it matches the connected repository and branch; never overwrite unrelated files or force-push. Do not clone into a non-empty folder.
+    npx @backifydev/cli@latest connect --app <app-id> --organization <organization-id> --api https://api.backify.dev/api --pair <pairing-code>
 
-Run the initialization command supplied in the prompt. Read the installed AGENTS.md and BACKIFY-WORKFLOW.md before changing application code. Initialization installs this workflow alongside the persistent SDK instructions. Follow https://agent.backify.dev/v3 for instruction version 3; use the guide matching backify.json in an existing application. Do not silently upgrade its managed instruction version or overwrite instructions outside the managed block.
+If Pair is absent, omit --pair and use CLI browser login. Pairing expires after 15 minutes. Never record the code or setup prompt in project files, Git, prompt history, or logs. The CLI stores an application-scoped session outside the repository. If access expires, obtain a new setup prompt or use CLI browser login.
+
+Before connecting, inspect the current folder. If it is not a Git repository, is missing its .git directory or file, or has no Git remote, add --clone to the connect command. Default AI coding-tool directories and instruction files do not make a workspace an existing application. Run connect --clone in the current folder even when tool scaffolding exists, including configuration, rules, agents, skills, commands, prompts, and work/output directories. This is tool-independent: preserve the current tool's metadata and instructions regardless of its name; never delete or overwrite them to make the folder empty. The CLI recognizes empty directories of any name, hidden tool-metadata directories and files, Markdown instruction files, and default work/outputs directories, including their contents. It clones into a temporary folder, checks for file conflicts, and safely merges the repository into the current workspace. If actual application source or an existing .git is present, or repository files conflict with existing entries, stop and reconcile the workspace or use a new folder; never overwrite user work. In an existing repository with a remote, verify it matches the connected repository and branch; never overwrite unrelated files or force-push.
+
+Initialize using App Id from the copied prompt and the current tool selection:
+
+    npx @backifydev/cli@latest init --app <app-id> --agent <current-tool>
+
+For a tool without a built-in preset, replace --agent <current-tool> with --instruction-file <relative-path>. Read BACKIFY.md and the instruction file used by the current AI coding tool before changing application code. Create or update only instruction files used by that tool; never create files for other coding tools. Use --agent for a built-in tool preset or --instruction-file <relative-path> for the current tool's native instruction file, as described in the setup guide. Initialization installs this workflow alongside the persistent SDK instructions. Follow https://agent.backify.dev/v4 for instruction version 4; use the guide matching backify.json in an existing application. Do not silently upgrade its managed instruction version or overwrite instructions outside the managed block.
 
 Run the following to discover the connected hosting target, repository, branch, reports, releases, and deployment failures:
 
-    npx @backifydev/cli@0.3.0 status
+    npx @backifydev/cli@latest status
 
 Connection and initialization may proceed without application requirements. Then ask what to build if none were supplied; never invent requirements or record this setup text as a user requirement.
 
@@ -805,10 +813,20 @@ Connection and initialization may proceed without application requirements. Then
 
 For EVERY user request to build or modify this application, including the initial requirements supplied alongside or after setup, record only the user's own requirement text before changing application code. Submit the text through standard input to:
 
-    npx @backifydev/cli@0.3.0 prompt record --stdin --id <new-UUID> [--filename <basename> ...]
+    npx @backifydev/cli@latest prompt record --stdin --id <new-UUID> [--filename <basename> ...]
 
 Record requests separately and in order. Generate a new UUID per request and reuse that UUID on retries. Add one --filename argument per attachment, using only its basename. Never send attachment bodies, extracted text, images, full paths, assistant responses, tool output, secrets, connection commands, or this setup/pairing block. Filename arguments are metadata only; never read attachment bodies to submit them. If recording fails, retry or report the blocker; never silently claim a request was recorded.
 
+## Keep local source current
+
+Automatically run the following before editing code for every new build or modification request, after recording the user requirement. Connecting an existing Git repository also runs this safe update automatically. A new clone already contains the connected branch's current source.
+
+    npx @backifydev/cli@latest pull
+
+The CLI verifies the connected application, repository, branch, and repository root, fetches GitHub changes with a short-lived scoped credential, and fast-forwards only when the local working tree is clean and history has not diverged. It never switches branches, stashes, resets, rebases, discards files, or force-pushes automatically. If local or untracked changes would block an incoming update, or local commits diverge from GitHub, stop and explain the blocker; obtain explicit direction to reconcile it. Never continue editing against known stale source or claim a blocked pull succeeded. Already-current or locally-ahead source is left unchanged.
+
+This is automatic at connection and at the start of each agent task, not a background watcher. Do not pull during ongoing edits or overwrite unrelated local work.
+
 ## Build for the connected hosting target
 
 Inspect the framework, lockfile, scripts, configuration, and applicable repository instructions before editing. Preserve the existing framework. Use @backifydev/sdk for platform capabilities, verify API signatures against its installed types and https://docs.backify.dev/capabilities/, and do not directly provision external infrastructure.
@@ -821,11 +839,11 @@ Do not claim unsupported hosted server functions or SDK execution paths work. Re
 
 Run:
 
-    npx @backifydev/cli@0.3.0 report --check
+    npx @backifydev/cli@latest report --check
 
 Fix relevant failures, then commit only application changes for this request using a meaningful message. Never commit credentials or unrelated user changes. Then run:
 
-    npx @backifydev/cli@0.3.0 ship
+    npx @backifydev/cli@latest ship
 
 The CLI verifies the repository and branch, runs checks, pushes committed source using a short-lived repository-scoped credential, waits for the exact source's healthy preview, and publishes through existing Backify permissions and policy. It never stages or commits files, force-pushes, changes hosting, fabricates preview testing, or bypasses approval. Use --preview-only only when the user requests a preview.
 
@@ -835,7 +853,7 @@ These instructions are an explicit agent workflow, not a universal chat intercep
 `;
 
 // ../platform/dist/index.js
-var INSTRUCTION_VERSION = 3;
+var INSTRUCTION_VERSION = 4;
 var SDK_PACKAGE = "@backifydev/sdk";
 var DOCS_URL = "https://docs.backify.dev";
 var MAIL_LIMITS = Object.freeze({
@@ -908,7 +926,7 @@ Run relevant tests, typechecking, lint, and builds using the repository's script
 
 ## Connected application delivery
 
-For connected applications, follow \`BACKIFY-WORKFLOW.md\` and https://agent.backify.dev/v${INSTRUCTION_VERSION}/delivery.md before changing application code. Record every user build or modification request, including initial requirements, with attachment filenames only; never submit attachment contents or setup credentials. Verify checks and publish through the connected CLI workflow without bypassing testing, approval, or coding-tool permissions. Report only verified deployment URLs.
+For connected applications, follow \`BACKIFY.md\` and https://agent.backify.dev/v${INSTRUCTION_VERSION}/delivery.md before changing application code. Record every user build or modification request, including initial requirements, with attachment filenames only; never submit attachment contents or setup credentials. Verify checks and publish through the connected CLI workflow without bypassing testing, approval, or coding-tool permissions. Report only verified deployment URLs.
 
 ## Instruction maintenance
 
@@ -954,69 +972,105 @@ function validateConfig(value) {
     errors.push("appId must use the app_<id> format");
   if (!Number.isInteger(x.instructionVersion) || Number(x.instructionVersion) < 1)
     errors.push("instructionVersion must be a positive integer");
+  if (x.agent !== void 0 && !["codex", "claude", "copilot", "gemini", "custom"].includes(x.agent))
+    errors.push("agent must be codex, claude, copilot, gemini, or custom");
+  if (x.instructionFile !== void 0 && (typeof x.instructionFile !== "string" || !x.instructionFile.trim()))
+    errors.push("instructionFile must be a nonempty relative path");
   if (x.instructions?.preferBackifyCapabilities !== true)
     errors.push("instructions.preferBackifyCapabilities must be true");
   if (x.instructions?.allowDirectCloudInfrastructure !== false)
     errors.push("instructions.allowDirectCloudInfrastructure must be false");
   return errors;
 }
-var BACKIFY_SCHEMA = { $schema: "https://json-schema.org/draft/2020-12/schema", $id: `${DOCS_URL}/schema/backify.json`, type: "object", additionalProperties: false, required: ["$schema", "platform", "sdk", "appId", "instructionVersion", "docs", "instructions"], properties: { $schema: { const: `${DOCS_URL}/schema/backify.json` }, platform: { const: "backify" }, sdk: { const: SDK_PACKAGE }, appId: { type: "string", pattern: "^app_[A-Za-z0-9_-]+$" }, instructionVersion: { type: "integer", minimum: 1 }, docs: { type: "string", format: "uri" }, instructions: { type: "object", additionalProperties: false, required: ["preferBackifyCapabilities", "allowDirectCloudInfrastructure"], properties: { preferBackifyCapabilities: { const: true }, allowDirectCloudInfrastructure: { const: false } } } } };
+var BACKIFY_SCHEMA = { $schema: "https://json-schema.org/draft/2020-12/schema", $id: `${DOCS_URL}/schema/backify.json`, type: "object", additionalProperties: false, required: ["$schema", "platform", "sdk", "appId", "instructionVersion", "docs", "instructions"], properties: { $schema: { const: `${DOCS_URL}/schema/backify.json` }, platform: { const: "backify" }, sdk: { const: SDK_PACKAGE }, appId: { type: "string", pattern: "^app_[A-Za-z0-9_-]+$" }, instructionVersion: { type: "integer", minimum: 1 }, agent: { enum: ["codex", "claude", "copilot", "gemini", "custom"] }, instructionFile: { type: "string", minLength: 1 }, docs: { type: "string", format: "uri" }, instructions: { type: "object", additionalProperties: false, required: ["preferBackifyCapabilities", "allowDirectCloudInfrastructure"], properties: { preferBackifyCapabilities: { const: true }, allowDirectCloudInfrastructure: { const: false } } } } };
 
 // src/delivery.ts
 import { existsSync as existsSync2, readFileSync, writeFileSync as writeFileSync2 } from "node:fs";
-import { join } from "node:path";
+import { dirname as dirname2, join, relative as relativePath } from "node:path";
 import { createHash } from "node:crypto";
-var previousGeneratedWorkflowHashes = /* @__PURE__ */ new Set(["6eb280ae7bdb14c390011686c41400f59c023304c3015d8440b7e80aaafa1c11", "545e03a1d5b996ade179e0e60ed5c86accdadc1982c1c25efd094e34f72f47ee"]);
+var previousGeneratedWorkflowHashes = /* @__PURE__ */ new Set(["578dfb4c771c623fd04454e8a604efd701d5563d11e11191324862369bd24718", "6eb280ae7bdb14c390011686c41400f59c023304c3015d8440b7e80aaafa1c11", "545e03a1d5b996ade179e0e60ed5c86accdadc1982c1c25efd094e34f72f47ee"]);
 function validateDeliveryInstructions(root) {
-  const path = join(root, "BACKIFY-WORKFLOW.md");
-  if (existsSync2(path)) {
-    const existing = readFileSync(path, "utf8").replace(/\r\n/g, "\n");
-    if (existing !== deliveryInstructions && !previousGeneratedWorkflowHashes.has(createHash("sha256").update(existing).digest("hex"))) throw new Error("BACKIFY-WORKFLOW.md contains different instructions. Review it before initializing; it will not be overwritten.");
+  for (const filename of ["BACKIFY.md", "BACKIFY-WORKFLOW.md"]) {
+    const path = join(root, filename);
+    if (existsSync2(path)) {
+      const existing = readFileSync(path, "utf8").replace(/\r\n/g, "\n");
+      if (existing !== deliveryInstructions && !previousGeneratedWorkflowHashes.has(createHash("sha256").update(existing).digest("hex"))) throw new Error(filename + " contains different instructions. Review it before initializing; it will not be overwritten.");
+    }
   }
 }
 function installDeliveryInstructions(root, instructionFiles2) {
   validateDeliveryInstructions(root);
-  const path = join(root, "BACKIFY-WORKFLOW.md");
-  writeFileSync2(path, deliveryInstructions);
+  writeFileSync2(join(root, "BACKIFY.md"), deliveryInstructions);
   for (const relative of instructionFiles2) {
     const instructionPath = join(root, relative), content = readFileSync(instructionPath, "utf8");
-    if (content.includes("## Backify delivery")) continue;
-    const link = relative.startsWith(".github") ? "../BACKIFY-WORKFLOW.md" : "BACKIFY-WORKFLOW.md";
-    writeFileSync2(instructionPath, content.trimEnd() + "\n\n## Backify delivery\n\nFor application delivery and recording each user request, follow [BACKIFY-WORKFLOW.md](" + link + ").\n");
+    const link = relativePath(dirname2(instructionPath), join(root, "BACKIFY.md")).replaceAll("\\", "/");
+    const legacyLink = relativePath(dirname2(instructionPath), join(root, "BACKIFY-WORKFLOW.md")).replaceAll("\\", "/");
+    const legacy = "For application delivery and recording each user request, follow [BACKIFY-WORKFLOW.md](" + legacyLink + ").";
+    const guidance = "For application delivery and recording each user request, follow [BACKIFY.md](" + link + ").";
+    if (content.includes(legacy)) writeFileSync2(instructionPath, content.replace(legacy, guidance));
+    else if (!content.includes("## Backify delivery")) writeFileSync2(instructionPath, content.trimEnd() + "\n\n## Backify delivery\n\n" + guidance + "\n");
   }
 }
 
 // src/setup.ts
-var instructionFiles = ["AGENTS.md", "CLAUDE.md", join2(".github", "copilot-instructions.md")];
+var instructionFiles = ["AGENTS.md"];
+var agentInstructionFiles = { codex: "AGENTS.md", claude: "CLAUDE.md", copilot: join2(".github", "copilot-instructions.md"), gemini: "GEMINI.md" };
+function instructionSelection(root, agent, instructionFile) {
+  const configPath2 = join2(root, "backify.json"), configured = existsSync3(configPath2) ? JSON.parse(readFileSync2(configPath2, "utf8")) : {};
+  const custom = instructionFile ?? (agent === void 0 ? configured.instructionFile : void 0);
+  const selected = instructionFile !== void 0 ? "custom" : agent ?? configured.agent ?? "codex";
+  if (typeof selected !== "string" || selected !== "custom" && !Object.hasOwn(agentInstructionFiles, selected)) throw new Error("Select the current tool with --agent or --instruction-file <relative-path>.");
+  const filename = custom ?? agentInstructionFiles[selected];
+  if (typeof filename !== "string" || !filename.trim()) throw new Error("Select the current tool with --agent codex, claude, copilot, or gemini, or --instruction-file <relative-path> for any other tool.");
+  const normalized = filename.replaceAll("\\", "/"), parts = normalized.split("/");
+  if (isAbsolute(filename) || /^[A-Za-z]:/.test(filename) || parts.some((part) => !part || part === "." || part === ".." || part.toLowerCase() === ".git") || ["backify.md", "backify-workflow.md", "backify.json", "package.json", "package-lock.json"].includes(normalized.toLowerCase())) throw new Error("Instruction file must be a relative tool-instruction path inside the project, not Git metadata or a Backify configuration file.");
+  for (let index = 1; index <= parts.length; index++) {
+    const entry = join2(root, ...parts.slice(0, index));
+    try {
+      const metadata = lstatSync(entry);
+      if (metadata.isSymbolicLink() || index < parts.length && !metadata.isDirectory() || index === parts.length && !metadata.isFile()) throw new Error("Instruction file path cannot traverse symlinks or replace a directory.");
+    } catch (reason) {
+      if (reason.code !== "ENOENT") throw reason;
+    }
+  }
+  return { agent: selected, instructionFile: normalized, files: [normalized] };
+}
+function selectedInstructionFiles(root = process.cwd(), agent, instructionFile) {
+  return instructionSelection(root, agent, instructionFile).files;
+}
+function isToolWorkspaceEntry(entry, root = process.cwd()) {
+  if (entry.name.toLowerCase() === ".git" || entry.name.toLowerCase() === ".env" || entry.name.toLowerCase().startsWith(".env.")) return false;
+  return entry.isDirectory() && (entry.name.startsWith(".") || ["work", "outputs"].includes(entry.name) || readdirSync(join2(root, entry.name)).length === 0) || entry.isFile() && (entry.name.startsWith(".") || /\.(md|mdc)$/i.test(entry.name));
+}
 function detectPackageManager(root = process.cwd()) {
   for (const [file, name] of [["pnpm-lock.yaml", "pnpm"], ["yarn.lock", "yarn"], ["bun.lockb", "bun"], ["bun.lock", "bun"], ["package-lock.json", "npm"]]) if (existsSync3(join2(root, file))) return name;
   return "npm";
 }
-function updateInstructions(root = process.cwd()) {
-  const updates = instructionFiles.map((relative) => {
+function updateInstructions(root = process.cwd(), agent, instructionFile) {
+  const updates = selectedInstructionFiles(root, agent, instructionFile).map((relative) => {
     const path = join2(root, relative);
     return { path, content: updateManagedInstructions(existsSync3(path) ? readFileSync2(path, "utf8") : "") };
   });
   for (const { path, content } of updates) {
-    mkdirSync2(dirname2(path), { recursive: true });
+    mkdirSync2(dirname3(path), { recursive: true });
     writeFileSync3(path, content);
   }
 }
-function synchronize(root = process.cwd()) {
+function synchronize(root = process.cwd(), agent, instructionFile) {
   const path = join2(root, "backify.json");
   if (!existsSync3(path)) throw new Error("backify.json is missing; run backify init --app app_xxxxx");
   const value = JSON.parse(readFileSync2(path, "utf8")), issues = validateConfig(value);
   if (issues.length) throw new Error(issues.join("; "));
   if (value.instructionVersion > INSTRUCTION_VERSION) throw new Error("This app uses newer instructions. Install a matching or newer CLI before syncing.");
+  const selected = instructionSelection(root, agent, instructionFile);
   validateDeliveryInstructions(root);
-  updateInstructions(root);
-  installDeliveryInstructions(root, instructionFiles);
+  updateInstructions(root, selected.agent, selected.instructionFile);
+  installDeliveryInstructions(root, selected.files);
+  value.agent = selected.agent;
+  value.instructionFile = selected.instructionFile;
   value.instructionVersion = INSTRUCTION_VERSION;
   writeFileSync3(path, JSON.stringify(value, null, 2) + "\n");
 }
-function writeConfig(appId, root = process.cwd()) {
-  writeFileSync3(join2(root, "backify.json"), JSON.stringify(createConfig(appId), null, 2) + "\n");
-}
 function sdkInstalled(root = process.cwd()) {
   try {
     const pkg = JSON.parse(readFileSync2(join2(root, "package.json"), "utf8"));
@@ -1033,20 +1087,24 @@ function installSdk(root = process.cwd()) {
 function ensurePackageManifest(root) {
   const path = join2(root, "package.json");
   if (existsSync3(path)) return;
-  const setupFiles = /* @__PURE__ */ new Set([".git", ".gitignore", ".github", "AGENTS.md", "CLAUDE.md", "README.md", "LICENSE", "backify.json"]);
-  if (readdirSync(root).some((file) => !setupFiles.has(file))) throw new Error("package.json is missing. Run backify init from the existing application's JavaScript/TypeScript package directory, or start in an empty folder. See https://agent.backify.dev/");
+  const setupFiles = /* @__PURE__ */ new Set([".git", ".gitignore", ".github", "AGENTS.md", "CLAUDE.md", "GEMINI.md", "BACKIFY.md", "BACKIFY-WORKFLOW.md", "README.md", "LICENSE", "backify.json"]);
+  if (readdirSync(root, { withFileTypes: true }).some((entry) => !setupFiles.has(entry.name) && !isToolWorkspaceEntry(entry, root))) throw new Error("package.json is missing. Run backify init from the existing application's JavaScript/TypeScript package directory, or start in an empty folder. See https://agent.backify.dev/");
   const name = basename(resolve2(root)).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "backify-app";
   writeFileSync3(path, JSON.stringify({ name, version: "0.0.0", private: true, type: "module" }, null, 2) + "\n", { flag: "wx" });
 }
-function initialize(appId, root = process.cwd(), install = true) {
+function initialize(appId, root = process.cwd(), install = true, agent, instructionFile) {
   if (!/^app_[A-Za-z0-9_-]+$/.test(appId)) throw new Error("Provide an application ID using --app app_xxxxx");
+  const selected = instructionSelection(root, agent, instructionFile), files = selected.files;
+  validateDeliveryInstructions(root);
+  for (const relative of files) if (existsSync3(join2(root, relative))) updateManagedInstructions(readFileSync2(join2(root, relative), "utf8"));
   ensurePackageManifest(root);
   if (install) installSdk(root);
-  writeConfig(appId, root);
-  updateInstructions(root);
-  installDeliveryInstructions(root, instructionFiles);
+  const configPath2 = join2(root, "backify.json"), existing = existsSync3(configPath2) ? JSON.parse(readFileSync2(configPath2, "utf8")) : {};
+  writeFileSync3(configPath2, JSON.stringify({ ...existing, ...createConfig(appId), agent: selected.agent, instructionFile: selected.instructionFile }, null, 2) + "\n");
+  updateInstructions(root, selected.agent, selected.instructionFile);
+  installDeliveryInstructions(root, files);
 }
-function doctor(root = process.cwd()) {
+function doctor(root = process.cwd(), agent, instructionFile) {
   const issues = [], warnings = [];
   if (!sdkInstalled(root)) issues.push(`${SDK_PACKAGE} is not installed`);
   let config;
@@ -1057,7 +1115,13 @@ function doctor(root = process.cwd()) {
     issues.push("backify.json is missing or invalid JSON");
   }
   if (config && config.instructionVersion !== INSTRUCTION_VERSION) issues.push(`Repository instruction version ${config.instructionVersion}; CLI version ${INSTRUCTION_VERSION}. Use the matching CLI or run backify sync to upgrade.`);
-  for (const relative of instructionFiles) {
+  let files = instructionFiles;
+  try {
+    files = selectedInstructionFiles(root, agent, instructionFile);
+  } catch (reason) {
+    issues.push(reason instanceof Error ? reason.message : String(reason));
+  }
+  for (const relative of files) {
     const path = join2(root, relative);
     if (!existsSync3(path)) {
       issues.push(`${relative} is missing`);
@@ -1138,13 +1202,57 @@ function gitEnvironment(repository, token) {
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repository)) throw new Error("Invalid repository.");
   return { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_COUNT: "3", GIT_CONFIG_KEY_0: "http.https://github.com/" + repository + ".git.extraheader", GIT_CONFIG_VALUE_0: "Authorization: Basic " + Buffer.from("x-access-token:" + token).toString("base64"), GIT_CONFIG_KEY_1: "credential.helper", GIT_CONFIG_VALUE_1: "", GIT_CONFIG_KEY_2: "http.followRedirects", GIT_CONFIG_VALUE_2: "false" };
 }
+function validateCloneMerge(source, target) {
+  for (const entry of readdirSync2(source, { withFileTypes: true })) {
+    const destination = join3(target, entry.name);
+    let existing;
+    try {
+      existing = lstatSync2(destination);
+    } catch (reason) {
+      if (reason.code === "ENOENT") continue;
+      throw reason;
+    }
+    if (entry.isDirectory() && existing.isDirectory() && !existing.isSymbolicLink()) validateCloneMerge(join3(source, entry.name), destination);
+    else throw new Error("Clone conflicts with existing workspace entry: " + destination + ". Existing files are never overwritten; reconcile the conflict or use a new folder.");
+  }
+}
 async function cloneProject(call2, appId, root = process.cwd()) {
   const status = await call2("/apps/" + applicationGuid(appId) + "/developer");
   if (!status.repository || !status.branch || !status.workflowReady) throw new Error("Connect the repository in Backify and wait for workflow setup.");
-  if (readdirSync2(root).length) throw new Error("--clone requires an empty directory. Existing files are never overwritten.");
+  if (readdirSync2(root, { withFileTypes: true }).some((entry) => !isToolWorkspaceEntry(entry, root))) throw new Error("--clone requires an empty directory or a workspace containing only AI tool metadata and default work/outputs directories. Existing application files and Git repositories are never overwritten.");
   const credential = await call2("/apps/" + applicationGuid(appId) + "/developer/git-credential", { method: "POST" });
   if (credential.repository.toLowerCase() !== status.repository.toLowerCase()) throw new Error("Repository changed. Run connect again.");
-  git(["clone", "--single-branch", "--branch", status.branch, "--", "https://github.com/" + status.repository + ".git", "."], root, gitEnvironment(status.repository, credential.token));
+  const staging = mkdtempSync(join3(dirname4(resolve3(root)), ".backify-clone-"));
+  try {
+    git(["clone", "--single-branch", "--branch", status.branch, "--", "https://github.com/" + status.repository + ".git", "."], staging, gitEnvironment(status.repository, credential.token));
+    validateCloneMerge(staging, root);
+    for (const entry of readdirSync2(staging)) cpSync(join3(staging, entry), join3(root, entry), { recursive: true, force: false, errorOnExist: true, dereference: false });
+  } finally {
+    if (dirname4(staging) !== dirname4(resolve3(root)) || !staging.startsWith(join3(dirname4(resolve3(root)), ".backify-clone-"))) throw new Error("Refusing to clean up an unexpected clone staging path.");
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+async function pullProject(call2, appId, root = process.cwd()) {
+  if (existsSync4(join3(root, "backify.json")) && applicationGuid(projectApplication(root)) !== applicationGuid(appId)) throw new Error("Local application ID does not match the connected application.");
+  const prefix = "/apps/" + applicationGuid(appId);
+  const status = await call2(prefix + "/developer");
+  if (!status.repository || !status.branch) throw new Error("Connect the repository and branch in Backify before pulling.");
+  if (resolve3(git(["rev-parse", "--show-toplevel"], root)) !== resolve3(root)) throw new Error("Run pull from the connected repository root.");
+  if (repositoryName(git(["remote", "get-url", "origin"], root)) !== status.repository.toLowerCase()) throw new Error("Local origin does not match the repository connected in Backify.");
+  if (git(["branch", "--show-current"], root) !== status.branch) throw new Error("Local branch does not match the branch connected in Backify. The CLI never switches branches automatically.");
+  git(["check-ref-format", "--branch", status.branch], root);
+  const credential = await call2(prefix + "/developer/git-credential", { method: "POST" });
+  if (credential.repository.toLowerCase() !== status.repository.toLowerCase()) throw new Error("Repository changed; reconnect before pulling.");
+  git(["fetch", "--no-tags", "--", "https://github.com/" + status.repository + ".git", "refs/heads/" + status.branch + ":refs/remotes/origin/" + status.branch], root, gitEnvironment(status.repository, credential.token));
+  const remoteCommit = git(["rev-parse", "FETCH_HEAD"], root);
+  const counts = git(["rev-list", "--left-right", "--count", "HEAD..." + remoteCommit], root).split(/\s+/).map(Number);
+  if (counts.length !== 2 || counts.some((count) => !Number.isSafeInteger(count) || count < 0)) throw new Error("Could not compare local and remote history.");
+  const [ahead, behind] = counts;
+  if (!behind) return { status: "up-to-date", ahead, behind, commit: git(["rev-parse", "HEAD"], root) };
+  if (ahead) return { status: "blocked", reason: "Local and GitHub history have diverged. Review and reconcile them explicitly; no rebase, reset, or force-push was performed.", ahead, behind };
+  if (git(["status", "--porcelain"], root)) return { status: "blocked", reason: "Local changes or untracked files are present. Commit, ignore, or otherwise resolve them explicitly before updating; nothing was stashed or overwritten.", ahead, behind };
+  git(["merge", "--ff-only", "--", remoteCommit], root);
+  return { status: "updated", ahead: 0, behind: 0, commit: git(["rev-parse", "HEAD"], root) };
 }
 async function readPrompt(input) {
   const chunks = [];
@@ -1369,15 +1477,15 @@ async function main() {
       break;
     }
     case "init":
-      initialize(option("--app") ?? args.find((value) => !value.startsWith("-")) ?? "");
+      initialize(option("--app") ?? args.find((value) => !value.startsWith("-")) ?? "", process.cwd(), true, option("--agent"), option("--instruction-file"));
       console.log("Backify initialized. SDK, delivery instructions, and prompt history guidance are ready.");
       break;
     case "sync":
-      synchronize();
+      synchronize(process.cwd(), option("--agent"), option("--instruction-file"));
       console.log("Backify instructions synchronized to version " + INSTRUCTION_VERSION);
       break;
     case "doctor": {
-      const result = doctor();
+      const result = doctor(process.cwd(), option("--agent"), option("--instruction-file"));
       console.log(JSON.stringify(result, null, 2));
       if (!result.valid) process.exitCode = 1;
       break;
@@ -1415,6 +1523,11 @@ async function main() {
       userConfig.sessions[key] = session;
       saveUserConfig(configPath, userConfig);
       if (args.includes("--clone")) await cloneProject(client, appId);
+      else if (existsSync5(join4(process.cwd(), ".git"))) {
+        const update = await pullProject(client, appId);
+        console.log(JSON.stringify(update, null, 2));
+        if (update.status === "blocked") throw new Error(update.reason);
+      }
       console.log(JSON.stringify(await client("/apps/" + applicationGuid(appId) + "/developer"), null, 2));
       break;
     }
@@ -1424,6 +1537,12 @@ async function main() {
       saveUserConfig(configPath, userConfig);
       console.log("Application CLI sessions revoked.");
       break;
+    case "pull": {
+      const result = await pullProject(call, option("--app") ?? projectApplication());
+      console.log(JSON.stringify(result, null, 2));
+      if (result.status === "blocked") process.exitCode = 1;
+      break;
+    }
     case "status": {
       const prefix = "/apps/" + applicationGuid(option("--app") ?? projectApplication());
       console.log(JSON.stringify(await call(prefix + "/developer"), null, 2));
@@ -1492,7 +1611,7 @@ async function main() {
       console.log(await call("/apps/" + applicationGuid(args[0]) + "/deployments/preview", { method: "POST", body: JSON.stringify({ sourceRevision: args[1] ?? "latest" }) }));
       break;
     default:
-      console.log("backify connect | init | doctor | sync | login | logout | disconnect | status | report [--check] | prompt record --stdin --id <UUID> | ship [--preview-only] | request | events environments|inspect|test | apps | deploy");
+      console.log("backify connect | init | doctor | sync | login | logout | disconnect | status | pull | report [--check] | prompt record --stdin --id <UUID> | ship [--preview-only] | request | events environments|inspect|test | apps | deploy");
   }
 }
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backifydev/cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Command-line setup and diagnostics for Backify applications",
   "type": "module",
   "bin": {