@tenonhq/dovetail-core 0.0.97 → 0.0.99

package/dist/appUtils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.processManifest = exports.normalizeManifestKeys = exports.toSafeFolderName = void 0;
+exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.processManifest = exports.normalizeManifestKeys = exports.toSafeFolderName = exports.stampMetadataContent = void 0;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const progress_1 = __importDefault(require("progress"));
@@ -62,6 +62,14 @@ const getUpdateSetConfig = () => {
     }
     return {};
 };
+// Strip the ServiceNow instance host from an absolute _record_link, leaving the
+// instance-relative path. The CADSO metadata endpoint returns an absolute URL
+// (https://<instance>.service-now.com/<table>.do?sys_id=...); persisting that
+// makes the on-disk artifact instance-bound, so a re-pull from a different
+// instance rewrites every metaData.json with the new host. The relative path
+// (/<table>.do?sys_id=...) resolves against whatever instance the reader is on.
+// Matches any *.service-now.com host so the output is portable across instances.
+const stripRecordLinkHost = (link) => link.replace(/^https?:\/\/[^/]+\.service-now\.com/i, "");
 // Merge _lastUpdatedOn into the server-provided metadata content. Preserves all
 // record fields (sys_id, sys_scope, field value/display_value pairs, etc.) so
 // the local metaData.json is a full snapshot of the record, not just a stub.
@@ -80,6 +88,9 @@ const stampMetadataContent = (file) => {
         else {
             metadata._lastUpdatedOn = stamp;
         }
+        if (typeof metadata._record_link === "string") {
+            metadata._record_link = stripRecordLinkHost(metadata._record_link);
+        }
         return { ...file, content: JSON.stringify(metadata, null, 2) };
     }
     catch (e) {
@@ -87,6 +98,7 @@ const stampMetadataContent = (file) => {
         return file;
     }
 };
+exports.stampMetadataContent = stampMetadataContent;
 const hasServerMetadata = (files) => files.some((f) => f.name === "metaData" && f.type === "json" && !!f.content);
 const processFilesInManRec = async (recPath, rec, forceWrite) => {
     FileLogger_1.fileLogger.debug("Processing record: " + rec.name + " (" + rec.files.length + " files)");
@@ -101,7 +113,7 @@ const processFilesInManRec = async (recPath, rec, forceWrite) => {
         };
         await fileWrite(stubMetadata, recPath);
     }
-    const writeResults = await (0, genericUtils_1.allSettledBatched)(rec.files, constants_1.CONCURRENCY_FILES, function (file) { return fileWrite(stampMetadataContent(file), recPath); });
+    const writeResults = await (0, genericUtils_1.allSettledBatched)(rec.files, constants_1.CONCURRENCY_FILES, function (file) { return fileWrite((0, exports.stampMetadataContent)(file), recPath); });
     const writeFailures = writeResults.filter((r) => r.status === "rejected");
     if (writeFailures.length > 0) {
         writeFailures.forEach((f) => {
@@ -572,7 +584,7 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
                 if (anyChanged || forceWrite) {
                     let metadataFile;
                     if (metadataFiles.length > 0 && metadataFiles[0].content) {
-                        metadataFile = stampMetadataContent(metadataFiles[0]);
+                        metadataFile = (0, exports.stampMetadataContent)(metadataFiles[0]);
                     }
                     else {
                         metadataFile = {

package/dist/bootstrap.js

@@ -40,7 +40,15 @@ exports.init = init;
 const dotenv_1 = __importDefault(require("dotenv"));
 const ConfigManager = __importStar(require("./config"));
 const Logger_1 = require("./Logger");
+const envArg_1 = require("./envArg");
 async function init() {
+    // Honor a per-command `--env <path>` override before config/env load so
+    // dotenv reads the requested file. Resolved here (not in loadConfigs) because
+    // the override must be set before loadEnvPath runs inside loadConfigs.
+    const envArg = (0, envArg_1.parseEnvArg)(process.argv.slice(2));
+    if (envArg) {
+        ConfigManager.setEnvPathOverride((0, envArg_1.resolveEnvArgPath)(envArg));
+    }
     let configLoaded = false;
     try {
         await ConfigManager.loadConfigs();

package/dist/commander.js

@@ -24,6 +24,12 @@ async function initCommands() {
         },
     };
     yargs_1.default
+        .option("env", {
+        alias: "e",
+        type: "string",
+        describe: "Path to a .env file to load for this command (default: .env in the project root). Lets one checkout target multiple instances.",
+    })
+        .global("env")
         .command(["watch", "w", "watchAllScopes"], "Watch all scopes for file changes and sync to ServiceNow", (cmdArgs) => {
         cmdArgs.options({
             ...sharedOptions,

package/dist/config.js

@@ -48,6 +48,7 @@ exports.getSourcePath = getSourcePath;
 exports.getSourcePathForScope = getSourcePathForScope;
 exports.getBuildPath = getBuildPath;
 exports.getEnvPath = getEnvPath;
+exports.setEnvPathOverride = setEnvPathOverride;
 exports.getDiffPath = getDiffPath;
 exports.getDiffFile = getDiffFile;
 exports.getRefresh = getRefresh;
@@ -96,6 +97,7 @@ let config_path;
 let source_path;
 let build_path;
 let env_path;
+let env_path_override;
 let manifest_path;
 let diff_path;
 let diff_file;
@@ -188,6 +190,16 @@ function getEnvPath() {
         return env_path;
     throw new Error("Error getting env path");
 }
+/**
+ * @description Overrides the .env file the CLI loads for this invocation.
+ * Set from the per-command `--env` flag before loadConfigs() runs (see
+ * bootstrap.ts) so `loadEnvPath` resolves to the requested file. Pass an
+ * absolute path; relative resolution is handled by the caller (resolveEnvArgPath).
+ * @param {string} absolutePath - Absolute path to the .env file to load.
+ */
+function setEnvPathOverride(absolutePath) {
+    env_path_override = absolutePath;
+}
 function getDiffPath() {
     if (diff_path)
         return diff_path;
@@ -535,6 +547,13 @@ async function loadBuildPath() {
 }
 async function loadEnvPath() {
     let rootDir = getRootDir();
+    // A per-command `--env` override wins over the project-root .env so a single
+    // checkout can target multiple instances by pointing at different credential
+    // files. The override is already resolved to an absolute path by the caller.
+    if (env_path_override) {
+        env_path = env_path_override;
+        return;
+    }
     env_path = path_1.default.join(rootDir, ".env");
 }
 async function loadManifestPath() {

package/dist/envArg.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseEnvArg = parseEnvArg;
+exports.resolveEnvArgPath = resolveEnvArgPath;
+const path_1 = __importDefault(require("path"));
+/**
+ * Per-invocation .env selection for the `dove` CLI.
+ *
+ * Every command accepts `--env <path>` (alias `-e`, also `--env-file` /
+ * `--envFile`) so a single checkout can target multiple instances by pointing
+ * at different credential files, e.g.:
+ *
+ *   npx dove push --env .env.prod
+ *   npx dove status -e ../envs/workshop.env
+ *
+ * The flag is parsed from raw argv before config/env load (see bootstrap.ts)
+ * and also registered as a global yargs option so it appears in `--help`.
+ */
+// Flag spellings that select an env file. `-e` is the short alias.
+var ENV_FLAGS = ["--env", "--env-file", "--envFile", "-e"];
+/**
+ * @description Extracts the env-file path from a raw argv slice. Supports both
+ * `--env <path>` and `--env=<path>` (and the `-e` / `--env-file` spellings).
+ * Returns the last occurrence so a later flag overrides an earlier one.
+ * @param {string[]} argv - Arguments after the node + script entries (process.argv.slice(2)).
+ * @returns {string|undefined} The raw path string, or undefined when absent.
+ */
+function parseEnvArg(argv) {
+    var found;
+    for (var i = 0; i < argv.length; i++) {
+        var arg = argv[i];
+        // `--env=path` / `-e=path`
+        var eq = arg.match(/^(--env|--env-file|--envFile|-e)=(.*)$/);
+        if (eq) {
+            found = eq[2];
+            continue;
+        }
+        // `--env path` / `-e path`
+        if (ENV_FLAGS.indexOf(arg) !== -1) {
+            var next = argv[i + 1];
+            if (typeof next === "string" && next.charAt(0) !== "-") {
+                found = next;
+                i++;
+            }
+        }
+    }
+    if (found === undefined || found === "")
+        return undefined;
+    return found;
+}
+/**
+ * @description Resolves a raw env-file argument to an absolute path. Relative
+ * paths resolve against the directory the command was run from (cwd), matching
+ * where the user typed the path.
+ * @param {string} rawPath - The value returned by parseEnvArg.
+ * @param {string} [cwd] - Base directory for relative paths (defaults to process.cwd()).
+ * @returns {string} An absolute path to the requested .env file.
+ */
+function resolveEnvArgPath(rawPath, cwd) {
+    if (path_1.default.isAbsolute(rawPath))
+        return rawPath;
+    return path_1.default.resolve(cwd || process.cwd(), rawPath);
+}

package/dist/initSystem/orchestrator.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -12,8 +45,24 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const Logger_1 = require("../Logger");
 const FileUtils_1 = require("../FileUtils");
+const ConfigManager = __importStar(require("../config"));
 const discovery_1 = require("./discovery");
 const corePlugin_1 = require("./corePlugin");
+/**
+ * @description Resolves the .env file login should read from and write to,
+ * honoring a per-command `--env` override when one is set. Falls back to
+ * <rootDir>/.env when config hasn't loaded an override.
+ * @param {string} rootDir - Project root used for the default .env location.
+ * @returns {string} Absolute path to the target .env file.
+ */
+function resolveLoginEnvPath(rootDir) {
+    try {
+        return ConfigManager.getEnvPath();
+    }
+    catch (e) {
+        return path_1.default.resolve(rootDir, ".env");
+    }
+}
 // ============================================================================
 // Init Context
 // ============================================================================
@@ -24,7 +73,7 @@ const corePlugin_1 = require("./corePlugin");
  */
 function buildInitContext(plugins) {
     const rootDir = process.cwd();
-    const envPath = path_1.default.resolve(rootDir, ".env");
+    const envPath = resolveLoginEnvPath(rootDir);
     const env = {};
     // Load existing .env values
     try {
@@ -254,10 +303,11 @@ function saveEnvVars(context, plugins) {
         .filter(key => context.env[key])
         .map(key => ({ key, value: context.env[key] }));
     if (vars.length > 0) {
-        (0, FileUtils_1.writeEnvVars)({ vars });
+        const envPath = resolveLoginEnvPath(process.cwd());
+        (0, FileUtils_1.writeEnvVars)({ vars, envPath });
         // Also set on process.env for immediate use
         vars.forEach(({ key, value }) => { process.env[key] = value; });
-        Logger_1.logger.success(chalk_1.default.green("✓ Saved to .env (existing values preserved)"));
+        Logger_1.logger.success(chalk_1.default.green("✓ Saved to " + path_1.default.basename(envPath) + " (existing values preserved)"));
     }
 }
 async function runInit(options) {

package/dist/tests/envArg.test.js

@@ -0,0 +1,49 @@
+"use strict";
+// Tests for the per-command `--env` flag parser (envArg.ts). Covers the flag
+// spellings (--env, --env-file, --envFile, -e), `=` and space-separated forms,
+// last-wins precedence, absence, and absolute/relative path resolution.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const envArg_1 = require("../envArg");
+describe("parseEnvArg", function () {
+    it("returns undefined when no env flag is present", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--diff", "main"])).toBeUndefined();
+    });
+    it("parses --env <path> (space-separated)", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--env", ".env.prod"])).toBe(".env.prod");
+    });
+    it("parses --env=<path>", function () {
+        expect((0, envArg_1.parseEnvArg)(["status", "--env=../envs/workshop.env"])).toBe("../envs/workshop.env");
+    });
+    it("parses the -e short alias (space and = forms)", function () {
+        expect((0, envArg_1.parseEnvArg)(["status", "-e", ".env.dev"])).toBe(".env.dev");
+        expect((0, envArg_1.parseEnvArg)(["status", "-e=.env.dev"])).toBe(".env.dev");
+    });
+    it("parses --env-file and --envFile spellings", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--env-file", "a.env"])).toBe("a.env");
+        expect((0, envArg_1.parseEnvArg)(["push", "--envFile", "b.env"])).toBe("b.env");
+    });
+    it("takes the last occurrence when the flag is repeated", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--env", "first.env", "--env", "second.env"])).toBe("second.env");
+    });
+    it("ignores a bare --env with no following value", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--env"])).toBeUndefined();
+    });
+    it("does not consume the next token when it looks like another flag", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--env", "--ci"])).toBeUndefined();
+    });
+    it("treats an empty --env= as absent", function () {
+        expect((0, envArg_1.parseEnvArg)(["push", "--env="])).toBeUndefined();
+    });
+});
+describe("resolveEnvArgPath", function () {
+    it("returns absolute paths unchanged", function () {
+        expect((0, envArg_1.resolveEnvArgPath)("/abs/path/.env", "/cwd")).toBe("/abs/path/.env");
+    });
+    it("resolves relative paths against the provided cwd", function () {
+        expect((0, envArg_1.resolveEnvArgPath)(".env.prod", "/projects/sn")).toBe(path_1.default.join("/projects/sn", ".env.prod"));
+    });
+});

package/dist/tests/stampMetadataContent.test.js

@@ -0,0 +1,62 @@
+"use strict";
+// Tests for stampMetadataContent — the writer that finalizes each record's
+// metaData.json before it lands on disk.
+//
+// Two on-disk-stability concerns are covered:
+//   1. _lastUpdatedOn is sourced from the record's sys_updated_on (stable across
+//      re-pulls) rather than a fresh wall-clock stamp.
+//   2. _record_link is rewritten to an instance-relative path. The CADSO metadata
+//      endpoint returns an absolute URL (https://<instance>.service-now.com/...);
+//      persisting the host makes the artifact instance-bound and dirties every
+//      file on a re-pull from a different instance. Stripping any *.service-now.com
+//      host keeps the diff to genuine schema changes.
+Object.defineProperty(exports, "__esModule", { value: true });
+const appUtils_1 = require("../appUtils");
+const metaFile = (content) => ({
+    name: "metaData",
+    type: "json",
+    content: JSON.stringify(content),
+});
+const parse = (file) => JSON.parse(file.content);
+describe("stampMetadataContent — _record_link host stripping", () => {
+    it("strips the configured workstudio host, leaving the relative path", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            sys_updated_on: { value: "2025-08-21 17:09:02" },
+            _record_link: "https://tenonworkstudio.service-now.com/sys_hub_action_input.do?sys_id=85de623c33ef2a107b18bc534d5c7b92",
+        }));
+        expect(parse(out)._record_link).toBe("/sys_hub_action_input.do?sys_id=85de623c33ef2a107b18bc534d5c7b92");
+    });
+    it("strips any *.service-now.com host (instance-portable)", () => {
+        for (const host of ["tenonworkshop", "tenon", "tenonworkbench"]) {
+            const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+                _record_link: `https://${host}.service-now.com/x_cadso_core_setting.do?sys_id=abc`,
+            }));
+            expect(parse(out)._record_link).toBe("/x_cadso_core_setting.do?sys_id=abc");
+        }
+    });
+    it("leaves an already-relative _record_link untouched (idempotent)", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({ _record_link: "/sys_hub_action_input.do?sys_id=abc" }));
+        expect(parse(out)._record_link).toBe("/sys_hub_action_input.do?sys_id=abc");
+    });
+    it("leaves records without a _record_link unchanged", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({ sys_updated_on: { value: "2025-08-21 17:09:02" } }));
+        expect(parse(out)._record_link).toBeUndefined();
+    });
+    it("ignores a non-string _record_link rather than throwing", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({ _record_link: null }));
+        expect(parse(out)._record_link).toBeNull();
+    });
+    it("still sources _lastUpdatedOn from sys_updated_on while stripping the host", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            sys_updated_on: { value: "2025-08-21 17:09:02" },
+            _record_link: "https://tenonworkstudio.service-now.com/incident.do?sys_id=1",
+        }));
+        const parsed = parse(out);
+        expect(parsed._lastUpdatedOn).toBe("2025-08-21 17:09:02");
+        expect(parsed._record_link).toBe("/incident.do?sys_id=1");
+    });
+    it("passes through non-metaData files verbatim", () => {
+        const script = { name: "script", type: "js", content: "var x = 1;" };
+        expect((0, appUtils_1.stampMetadataContent)(script)).toEqual(script);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-core",
-  "version": "0.0.97",
+  "version": "0.0.99",
   "description": "Next-gen file syncer",
   "license": "GPL-3.0",
   "main": "./dist/index.js",

package/release-manifest.json

@@ -1,7 +1,111 @@
 {
   "$schema": "dovetail-manifest/v1",
-  "generated_at": "2026-06-01T21:28:08.741Z",
+  "generated_at": "2026-06-02T17:01:03.752Z",
   "events": [
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-servicenow@0.0.13",
+      "package": "@tenonhq/dovetail-servicenow",
+      "version": "0.0.13",
+      "prev_version": "0.0.12",
+      "published_at": "2026-06-02T17:01:03.745Z",
+      "git": {
+        "sha": "db8fddb963948f013aacfc6f67b26773234ef39d",
+        "tag": "dovetail-servicenow@0.0.13"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "db8fddb96",
+          "subject": "feat(servicenow): create-flow — mint + publish a whole flow from scratch (#138)",
+          "pr": 138
+        },
+        {
+          "sha": "bd127c726",
+          "subject": "chore(release): @tenonhq/dovetail-servicenow@0.0.12 [skip ci]"
+        },
+        {
+          "sha": "448696846",
+          "subject": "chore(release): publish 3 packages [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-servicenow@0.0.12",
+      "package": "@tenonhq/dovetail-servicenow",
+      "version": "0.0.12",
+      "prev_version": "0.0.11",
+      "published_at": "2026-06-02T16:06:43.535Z",
+      "git": {
+        "sha": "73ad931dbda5cdf85d4bc91307a17eb4d08de3d2",
+        "tag": "dovetail-servicenow@0.0.12"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "73ad931db",
+          "subject": "docs: point SN env-var references at committed .env.example (#137)",
+          "pr": 137
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-schema@0.0.10",
+      "package": "@tenonhq/dovetail-schema",
+      "version": "0.0.10",
+      "prev_version": "0.0.9",
+      "published_at": "2026-06-02T14:03:06.699Z",
+      "git": {
+        "sha": "9a243fd936caa778def575de19c79d978b65f5ac",
+        "tag": "dovetail-schema@0.0.10"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "9a243fd93",
+          "subject": "fix(schema): stop stamping created_at/generated_at into schema pull output (#135)",
+          "pr": 135
+        },
+        {
+          "sha": "407d6d75e",
+          "subject": "chore(release): publish 2 packages [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-core@0.0.97",
+      "package": "@tenonhq/dovetail-core",
+      "version": "0.0.97",
+      "prev_version": "0.0.96",
+      "published_at": "2026-06-01T23:57:01.670Z",
+      "git": {
+        "sha": "a0c364c7070a82f70c5dc9eed01c29c61b2f8b56",
+        "tag": "dovetail-core@0.0.97"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "a0c364c70",
+          "subject": "fix: route refresh folder writes through toSafeFolderName (Windows-safe names) (#133)",
+          "pr": 133
+        },
+        {
+          "sha": "958f4fcd7",
+          "subject": "chore(release): publish 3 packages [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
     {
       "$schema": "dovetail-release-event/v1",
       "event_id": "dovetail-core@0.0.96",

package/skills/dove-setup-project.md

@@ -56,6 +56,7 @@ SN_INSTANCE=your-instance.service-now.com
 - Instance should NOT have `https://` prefix or trailing slash
 - Optional: `DASHBOARD_PORT=3456`
 - **Never commit `.env` to git**
+- **Multiple instances?** Keep one file per instance (`.env.dev`, `.env.prod`) and pass `--env <path>` (alias `-e`) on any command: `npx dove push --env .env.prod`. `dove login --env .env.prod` writes credentials to that file too. Git-ignore the whole pattern (`.env*`).
 
 #### Set up `.gitignore`
 ```

package/skills/dove-troubleshoot-sync.md

@@ -49,10 +49,12 @@ Ask the user which symptom they are experiencing (if not already clear):
    - Instance should NOT have `https://` prefix or trailing slash
    - Credentials must have admin or developer role
 
-2. **Test connection:** `npx dove status`
+2. **Test connection:** `npx dove status` (add `--env <path>` to test a specific credential file, e.g. `npx dove status --env .env.prod`)
 
 3. **Check the Dovetail server scoped app** is installed on the instance. Without it, API endpoints will 404.
 
+   - **Hitting the wrong instance?** A stray `.env` in the working directory — or a shell-exported `SN_INSTANCE` — can override the file you expect. Pass `--env <path>` to load credentials from a specific file (every `dove` command accepts it; alias `-e`). Already-set environment variables still win, so unset conflicting `SN_*` vars if needed.
+
 4. **Check for MFA/SSO:** If the instance uses MFA or SSO, basic auth may not work. You may need a local ServiceNow account.
 
 ### Diagnostic C: Scope Mismatch