@specific.dev/cli 0.1.183 → 0.1.185

package/dist/cli.js

@@ -368225,6 +368225,14 @@ async function createTarball(config, projectDir) {
   return await createProjectTarball(projectDir, widestContext);
 }
 var import_hcl2_json_parser = __toESM2(require_dist(), 1);
+function extractEnvReferences(value) {
+  if (typeof value === "string")
+    return [];
+  if (value.type === "interpolated") {
+    return value.parts.filter((p) => p.type === "ref").map((p) => p.ref);
+  }
+  return [value];
+}
 var { parseToObject } = import_hcl2_json_parser.default;
 function parseReference(value) {
   if (typeof value !== "string") {
@@ -368996,19 +369004,11 @@ async function parseConfig(hcl) {
     environments: parseEnvironments(json.environment)
   };
 }
-function envValueReferences(value) {
-  if (typeof value === "string")
-    return [];
-  if (value.type === "interpolated") {
-    return value.parts.filter((p) => p.type === "ref").map((p) => p.ref);
-  }
-  return [value];
-}
 function hasPortReference(env2) {
   if (!env2)
     return false;
   for (const value of Object.values(env2)) {
-    for (const ref of envValueReferences(value)) {
+    for (const ref of extractEnvReferences(value)) {
       if (ref.type === "port")
         return true;
     }
@@ -369025,7 +369025,7 @@ function validateEndpointReferences(config) {
     if (!service.env)
       continue;
     for (const [key, value] of Object.entries(service.env)) {
-      const refs = envValueReferences(value);
+      const refs = extractEnvReferences(value);
       for (const ref of refs) {
         if (service.endpoints.length > 1 && ref.type === "port") {
           errors.push({
@@ -369104,6 +369104,82 @@ function validateEndpointReferences(config) {
   }
   return errors;
 }
+var UnknownServiceError = class extends Error {
+  unknownNames;
+  availableServices;
+  cronNames;
+  constructor(unknownNames, availableServices, cronNames) {
+    const plural = unknownNames.length > 1 ? "services" : "service";
+    const names = unknownNames.map((n) => `"${n}"`).join(", ");
+    const available = availableServices.length > 0 ? ` Available services: ${availableServices.join(", ")}` : " No services are defined in specific.hcl.";
+    super(`Unknown ${plural} ${names}.${available}`);
+    this.unknownNames = unknownNames;
+    this.availableServices = availableServices;
+    this.cronNames = cronNames;
+    this.name = "UnknownServiceError";
+  }
+};
+function resolveServiceClosure(config, roots, options2 = {}) {
+  const devMode = options2.devMode ?? true;
+  const byName = new Map(config.services.map((s) => [s.name, s]));
+  const dedupedRoots = [...new Set(roots)];
+  const unknown = dedupedRoots.filter((name) => !byName.has(name));
+  if (unknown.length > 0) {
+    throw new UnknownServiceError(unknown, [...byName.keys()], config.crons.map((c) => c.name));
+  }
+  const visited = new Set(dedupedRoots);
+  const queue = [...dedupedRoots];
+  const postgres = /* @__PURE__ */ new Set();
+  const redis = /* @__PURE__ */ new Set();
+  const storage = /* @__PURE__ */ new Set();
+  const temporal = /* @__PURE__ */ new Set();
+  const mail = /* @__PURE__ */ new Set();
+  const syncPostgres = /* @__PURE__ */ new Set();
+  const effectiveEnv = (service) => devMode ? { ...service.env, ...service.dev?.env } : { ...service.env };
+  while (queue.length > 0) {
+    const service = byName.get(queue.shift());
+    for (const value of Object.values(effectiveEnv(service))) {
+      for (const ref of extractEnvReferences(value)) {
+        switch (ref.type) {
+          case "service":
+            if (byName.has(ref.serviceName) && !visited.has(ref.serviceName)) {
+              visited.add(ref.serviceName);
+              queue.push(ref.serviceName);
+            }
+            break;
+          case "postgres":
+            postgres.add(ref.name);
+            if (ref.attribute === "sync.url" || ref.attribute === "sync.secret") {
+              syncPostgres.add(ref.name);
+            }
+            break;
+          case "redis":
+            redis.add(ref.name);
+            break;
+          case "storage":
+            storage.add(ref.name);
+            break;
+          case "temporal":
+            temporal.add(ref.name);
+            break;
+          case "mail":
+            mail.add(ref.name);
+            break;
+        }
+      }
+    }
+  }
+  const names = (items, set) => items.filter((item) => set.has(item.name)).map((item) => item.name);
+  return {
+    services: names(config.services, visited),
+    postgres: names(config.postgres, postgres),
+    redis: names(config.redis, redis),
+    storage: names(config.storage, storage),
+    temporal: names(config.temporal, temporal),
+    mail: names(config.mail, mail),
+    syncPostgres: names(config.postgres, syncPostgres)
+  };
+}
 function parseHclErrors(rawError) {
   const raw = rawError.trim();
   if (!raw.startsWith("parse config: [")) {
@@ -372588,7 +372664,7 @@ async function startResources(options2) {
     });
   }
   if (shouldStartElectric) {
-    const syncDatabases = detectSyncDatabases(config);
+    const syncDatabases = options2.syncDatabases ?? detectSyncDatabases(config);
     for (const pgName of syncDatabases) {
       if (signal?.cancelled) {
         return { resources, electric, mail: mailServers, startedResources, startedElectric, cancelled: true };
@@ -373087,9 +373163,11 @@ var DevEnvironment = class extends TypedEventEmitter {
   tunnelEnabled;
   preSuppliedSecrets;
   preSuppliedConfigs;
+  servicesFilter;
   // Status
   _status = "idle";
   _config;
+  _selection;
   // Guards
   started = false;
   shuttingDown = false;
@@ -373133,6 +373211,7 @@ var DevEnvironment = class extends TypedEventEmitter {
     this.tunnelEnabled = options2?.tunnel ?? false;
     this.preSuppliedSecrets = options2?.secrets ?? {};
     this.preSuppliedConfigs = options2?.configs ?? {};
+    this.servicesFilter = options2?.services ?? [];
   }
   // ── Public getters ─────────────────────────────────────────────────────────
   get status() {
@@ -373141,6 +373220,10 @@ var DevEnvironment = class extends TypedEventEmitter {
   get config() {
     return this._config;
   }
+  /** The resolved service selection when a services filter is active. */
+  get selection() {
+    return this._selection;
+  }
   // ── Status helper ──────────────────────────────────────────────────────────
   setStatus(status) {
     this._status = status;
@@ -373515,6 +373598,31 @@ var DevEnvironment = class extends TypedEventEmitter {
     }
     if (this.cancelled) return;
     this._config = config;
+    let closure;
+    if (this.servicesFilter.length > 0) {
+      try {
+        closure = resolveServiceClosure(config, this.servicesFilter);
+      } catch (err) {
+        let message = err instanceof Error ? err.message : String(err);
+        if (err instanceof UnknownServiceError) {
+          const crons = err.unknownNames.filter(
+            (n) => err.cronNames.includes(n)
+          );
+          for (const cron of crons) {
+            message += `
+"${cron}" is a cron \u2014 crons don't run in specific dev. Trigger it with: specific exec ${cron}`;
+          }
+        }
+        this.setStatus("error");
+        this.emit("error", new Error(message));
+        return;
+      }
+      this.systemLog(
+        `Starting ${closure.services.length} of ${config.services.length} services: ${closure.services.join(", ")}`
+      );
+    }
+    this._selection = closure;
+    const servicesToRun = closure ? config.services.filter((s) => closure.services.includes(s.name)) : config.services;
     this.colorMap = /* @__PURE__ */ new Map();
     let colorIndex = 0;
     for (const pg of config.postgres) {
@@ -373552,13 +373660,21 @@ var DevEnvironment = class extends TypedEventEmitter {
     this.setStatus("starting");
     const portAllocator = await BlockPortAllocator.create();
     this.systemLog(`Using port block ${portAllocator.getBasePort()}\u2013${portAllocator.getBasePort() + 99}`);
-    const syncDatabases = detectSyncDatabases(config);
+    const syncDatabases = closure ? new Set(closure.syncPostgres) : detectSyncDatabases(config);
     let resources;
     const startedElectric = [];
     try {
       const result = await startResources({
         config,
-        selection: { mode: "all" },
+        selection: closure ? {
+          mode: "required",
+          postgres: closure.postgres,
+          redis: closure.redis,
+          storage: closure.storage,
+          temporal: closure.temporal,
+          mail: closure.mail
+        } : { mode: "all" },
+        syncDatabases,
         stateManager,
         dataDir: `.specific/keys/${this.instanceKey}/data`,
         portAllocator,
@@ -373720,8 +373836,8 @@ var DevEnvironment = class extends TypedEventEmitter {
     if (this.cancelled) return;
     const secrets = await prepareSecrets(config.secrets, true);
     const configs = await prepareConfigs(config.configs, void 0, true);
-    const usedSecrets = findUsedSecrets(config.services, true);
-    const usedConfigs = findUsedConfigs(config.services, true);
+    const usedSecrets = findUsedSecrets(servicesToRun, true);
+    const usedConfigs = findUsedConfigs(servicesToRun, true);
     let missingSecrets = findMissingSecrets(
       config.secrets,
       secrets,
@@ -373805,7 +373921,7 @@ Add them to the config block in specific.local`
     }
     const serviceEndpoints = /* @__PURE__ */ new Map();
     const serviceEndpointPorts = /* @__PURE__ */ new Map();
-    for (const service of config.services) {
+    for (const service of servicesToRun) {
       if (!service.command && !service.dev?.command) continue;
       const endpointPorts = /* @__PURE__ */ new Map();
       const endpointInfos = [];
@@ -373832,7 +373948,7 @@ Add them to the config block in specific.local`
       serviceEndpoints.set(service.name, endpointInfos);
     }
     const exposedServices = [];
-    for (const service of config.services) {
+    for (const service of servicesToRun) {
       const endpointInfos = serviceEndpoints.get(service.name) || [];
       for (const info of endpointInfos) {
         const endpointConfig = service.endpoints.find(
@@ -373878,7 +373994,7 @@ Add them to the config block in specific.local`
       }
       return this.projectDir;
     };
-    for (const service of config.services) {
+    for (const service of servicesToRun) {
       if (this.cancelled) break;
       if (!service.command && !service.dev?.command) {
         continue;
@@ -373947,7 +374063,7 @@ Add them to the config block in specific.local`
       this.systemLog("Restarting services (migration changed)");
       await Promise.all(this.services.map((s) => s.stop()));
       const newServices = [];
-      for (const service of config.services) {
+      for (const service of servicesToRun) {
         if (!service.command && !service.dev?.command) continue;
         try {
           const endpointPorts = serviceEndpointPorts.get(service.name) || /* @__PURE__ */ new Map();
@@ -374770,7 +374886,7 @@ function trackEvent(event, properties) {
     event,
     properties: {
       ...properties,
-      cli_version: "0.1.183",
+      cli_version: "0.1.185",
       platform: process.platform,
       node_version: process.version,
       project_id: getProjectId()
@@ -376238,7 +376354,18 @@ function ConfigInput({ configName, defaultValue, onSubmit, onCancel }) {
 
 // src/commands/dev.tsx
 var COLORS2 = ["cyan", "yellow", "green", "magenta", "blue"];
-function DevUI({ instanceKey, tunnelEnabled }) {
+function filterConfigToSelection(config, selection) {
+  return {
+    ...config,
+    services: config.services.filter((s) => selection.services.includes(s.name)),
+    postgres: config.postgres.filter((p) => selection.postgres.includes(p.name)),
+    redis: config.redis.filter((r) => selection.redis.includes(r.name)),
+    storage: config.storage.filter((s) => selection.storage.includes(s.name)),
+    temporal: config.temporal.filter((t) => selection.temporal.includes(t.name)),
+    mail: config.mail.filter((m) => selection.mail.includes(m.name))
+  };
+}
+function DevUI({ instanceKey, tunnelEnabled, services: serviceFilter }) {
   const { exit } = useApp2();
   const [state, setState] = useState5({
     status: "loading",
@@ -376281,7 +376408,8 @@ function DevUI({ instanceKey, tunnelEnabled }) {
     const devEnv = new DevEnvironment({
       projectDir: process.cwd(),
       instanceKey,
-      tunnel: tunnelEnabled
+      tunnel: tunnelEnabled,
+      services: serviceFilter
     });
     devEnvRef.current = devEnv;
     let currentColorMap = /* @__PURE__ */ new Map();
@@ -376291,12 +376419,18 @@ function DevUI({ instanceKey, tunnelEnabled }) {
       } else if (status === "starting") {
         const config2 = devEnv.config;
         if (config2) {
-          currentColorMap = buildColorMap(config2);
+          const selection = devEnv.selection;
+          const displayConfig = selection ? filterConfigToSelection(config2, selection) : config2;
+          currentColorMap = buildColorMap(displayConfig);
           setState((s) => ({
             ...s,
             status: "starting",
-            config: config2,
-            colorMap: currentColorMap
+            config: displayConfig,
+            colorMap: currentColorMap,
+            filterInfo: selection ? {
+              selected: selection.services.length,
+              total: config2.services.length
+            } : void 0
           }));
         } else {
           setState((s) => ({ ...s, status: "starting" }));
@@ -376413,7 +376547,7 @@ function DevUI({ instanceKey, tunnelEnabled }) {
       devEnv.removeAllListeners();
       devEnvRef.current = null;
     };
-  }, [instanceKey, tunnelEnabled]);
+  }, [instanceKey, tunnelEnabled, serviceFilter.join(",")]);
   useEffect5(() => {
     const handleSignal = () => {
       const devEnv = devEnvRef.current;
@@ -376560,7 +376694,7 @@ function DevUI({ instanceKey, tunnelEnabled }) {
     return /* @__PURE__ */ React6.createElement(Box6, null, /* @__PURE__ */ React6.createElement(Text6, { color: "blue" }, /* @__PURE__ */ React6.createElement(Spinner3, { type: "dots" })));
   }
   if (state.status === "starting") {
-    return /* @__PURE__ */ React6.createElement(Box6, { flexDirection: "column" }, /* @__PURE__ */ React6.createElement(Text6, null, /* @__PURE__ */ React6.createElement(Text6, { bold: true, color: "cyan" }, "Specific dev server"), /* @__PURE__ */ React6.createElement(Text6, { dimColor: true }, " (Ctrl+C to stop)")), /* @__PURE__ */ React6.createElement(Text6, null, " "), (config.postgres.length > 0 || config.redis.length > 0 || config.storage.length > 0 || config.temporal.length > 0) && /* @__PURE__ */ React6.createElement(React6.Fragment, null, /* @__PURE__ */ React6.createElement(Text6, { bold: true }, "Resources:"), config.postgres.map((pg) => {
+    return /* @__PURE__ */ React6.createElement(Box6, { flexDirection: "column" }, /* @__PURE__ */ React6.createElement(Text6, null, /* @__PURE__ */ React6.createElement(Text6, { bold: true, color: "cyan" }, "Specific dev server"), state.filterInfo && /* @__PURE__ */ React6.createElement(Text6, { dimColor: true }, " ", "[", state.filterInfo.selected, " of ", state.filterInfo.total, " services]"), /* @__PURE__ */ React6.createElement(Text6, { dimColor: true }, " (Ctrl+C to stop)")), /* @__PURE__ */ React6.createElement(Text6, null, " "), (config.postgres.length > 0 || config.redis.length > 0 || config.storage.length > 0 || config.temporal.length > 0) && /* @__PURE__ */ React6.createElement(React6.Fragment, null, /* @__PURE__ */ React6.createElement(Text6, { bold: true }, "Resources:"), config.postgres.map((pg) => {
       const instance = resources.get(pg.name);
       const resStatus = state.resourceStatus.get(pg.name);
       const isReady = !!instance;
@@ -376625,7 +376759,7 @@ function DevUI({ instanceKey, tunnelEnabled }) {
   const staticItems = [
     {
       key: "title",
-      content: /* @__PURE__ */ React6.createElement(Text6, null, /* @__PURE__ */ React6.createElement(Text6, { bold: true, color: "cyan" }, "Specific dev server"), tunnelEnabled && /* @__PURE__ */ React6.createElement(Text6, { color: "magenta" }, " [tunnel]"), instanceKey !== "default" && /* @__PURE__ */ React6.createElement(Text6, { color: "yellow" }, " [", instanceKey, "]"), /* @__PURE__ */ React6.createElement(Text6, { dimColor: true }, " (Ctrl+C to stop)"))
+      content: /* @__PURE__ */ React6.createElement(Text6, null, /* @__PURE__ */ React6.createElement(Text6, { bold: true, color: "cyan" }, "Specific dev server"), tunnelEnabled && /* @__PURE__ */ React6.createElement(Text6, { color: "magenta" }, " [tunnel]"), instanceKey !== "default" && /* @__PURE__ */ React6.createElement(Text6, { color: "yellow" }, " [", instanceKey, "]"), state.filterInfo && /* @__PURE__ */ React6.createElement(Text6, { dimColor: true }, " ", "[", state.filterInfo.selected, " of ", state.filterInfo.total, " services]"), /* @__PURE__ */ React6.createElement(Text6, { dimColor: true }, " (Ctrl+C to stop)"))
     },
     { key: "space1", content: /* @__PURE__ */ React6.createElement(Text6, null, " ") },
     // Show admin UI URL
@@ -376735,10 +376869,20 @@ function DevUI({ instanceKey, tunnelEnabled }) {
   ];
   return /* @__PURE__ */ React6.createElement(Box6, { flexDirection: "column" }, /* @__PURE__ */ React6.createElement(Static, { items: staticItems }, (item) => /* @__PURE__ */ React6.createElement(Box6, { key: item.key }, item.content)));
 }
-function devCommand(instanceKey, tunnelEnabled = false) {
+function devCommand(instanceKey, tunnelEnabled = false, services = []) {
   const options2 = isInteractive() ? {} : { stdin: new Readable2({ read() {
   } }) };
-  render4(/* @__PURE__ */ React6.createElement(DevUI, { instanceKey, tunnelEnabled }), options2);
+  render4(
+    /* @__PURE__ */ React6.createElement(
+      DevUI,
+      {
+        instanceKey,
+        tunnelEnabled,
+        services
+      }
+    ),
+    options2
+  );
 }
 
 // src/commands/deploy.tsx
@@ -379157,7 +379301,7 @@ function compareVersions(a, b) {
   return 0;
 }
 async function checkForUpdate() {
-  const currentVersion = "0.1.183";
+  const currentVersion = "0.1.185";
   const response = await fetch(`${BINARIES_BASE_URL}/latest?t=${Date.now()}`);
   if (!response.ok) {
     throw new Error(`Failed to check for updates: HTTP ${response.status}`);
@@ -380074,7 +380218,7 @@ async function domainAddCommand(service, domain, options2) {
 var program = new Command();
 var env = "production";
 var envLabel = env !== "production" ? `[${env.toUpperCase()}] ` : "";
-program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.183").enablePositionalOptions();
+program.name("specific").description(`${envLabel}Infrastructure-as-code for coding agents`).version("0.1.185").enablePositionalOptions();
 program.command("init").description("Initialize project for use with a coding agent").option("--agent <name...>", "Agents to configure (cursor, claude, codex, other)").addHelpText("after", `
 Examples:
   $ specific init
@@ -380087,13 +380231,14 @@ Examples:
 program.command("check").description("Validate specific.hcl configuration").addHelpText("after", `
 Examples:
   $ specific check`).action(checkCommand);
-program.command("dev").description("Start local development environment").option("-k, --key <key>", "Namespace for isolated dev environment (auto-detected from git worktree if not specified)").option("--tunnel", "Expose public services via public *.tunnel.spcf.app URLs").addHelpText("after", `
+program.command("dev").description("Start local development environment").option("-k, --key <key>", "Namespace for isolated dev environment (auto-detected from git worktree if not specified)").option("--tunnel", "Expose public services via public *.tunnel.spcf.app URLs").option("--services <services...>", "Only start these services and everything they depend on").addHelpText("after", `
 Examples:
   $ specific dev
+  $ specific dev --services api worker
   $ specific dev --tunnel
   $ specific dev --key feature-branch`).action((options2) => {
   const key = options2.key ?? getDefaultKey();
-  devCommand(key, options2.tunnel ?? false);
+  devCommand(key, options2.tunnel ?? false, options2.services ?? []);
 });
 program.command("deploy").description("Deploy to Specific infrastructure").option("--project <id>", "Project ID to deploy to (overrides .projectid file)").option("-e, --environment <name|id>", "Target environment (auto-selected if only one exists)").option("--secret <key=value...>", "Secret values (repeatable)").option("--config <key=value...>", "Config values (repeatable)").option("--preview", "Deploy to an ephemeral preview environment").addHelpText("after", `
 Examples:

package/dist/docs/index.md

@@ -10,7 +10,7 @@ This documentation is nested and references to other docs are in Markdown link f
 2. ALWAYS run `specific check` to validate configuration and fix any issues
 3. Run yourself or instruct the user to run `specific exec [SERVICE] -- [COMMAND]` for one-off commands that need to be run in development, like database migrations or seeding. The command will be run with databases and other services started and env vars injected.
 
-A full development environment can be started with `specific dev`. To deploy any changes, the user can run `specific deploy`.
+A full development environment can be started with `specific dev`. To only run part of the system, pass `--services [SERVICE...]` — the named services start along with everything they depend on (referenced services and resources, transitively). To deploy any changes, the user can run `specific deploy`.
 
 If the project is connected to GitHub in the Specific Dashboard, pushes to the configured branch can deploy automatically. Run `specific status` to inspect the project and environment state. If a deploy fails — including GitHub-triggered deploys — run `specific deployment show` to see why, and add `--output` for the failed build's log.
 

package/dist/docs/postgres.md

@@ -45,6 +45,7 @@ The following PostgreSQL extensions are available in both development and produc
 - **PostGIS** (`postgis`) - Geospatial queries and indexing over geometry and geography types. Enable with `CREATE EXTENSION postgis;` in a migration. See https://postgis.net/documentation/ for full documentation.
 - **pg_trgm** (`pg_trgm`) - Trigram-based fuzzy text matching and `gin_trgm_ops` / `gist_trgm_ops` indexes for `LIKE`/`ILIKE`/similarity queries. Enable with `CREATE EXTENSION pg_trgm;` in a migration. See https://www.postgresql.org/docs/current/pgtrgm.html for full documentation.
 - **ltree** (`ltree`) - Hierarchical tree-like structures for categories, org charts, and taxonomies. Enable with `CREATE EXTENSION ltree;` in a migration. See https://www.postgresql.org/docs/current/ltree.html for full documentation.
+- **btree_gist** (`btree_gist`) - GiST operator classes for B-tree types (int, text, timestamp, uuid, ...), enabling exclusion constraints (e.g. preventing overlapping time ranges per resource) and multicolumn GiST indexes that mix scalar and GiST-native types. Enable with `CREATE EXTENSION btree_gist;` in a migration. See https://www.postgresql.org/docs/current/btree-gist.html for full documentation.
 - **pgRouting** (`pgrouting`) - Geospatial routing and network analysis for transportation networks, logistics, and path-finding. Requires PostGIS. Enable with `CREATE EXTENSION pgrouting CASCADE;` in a migration. See https://docs.pgrouting.org/ for full documentation.
 
 ## Graph data

package/dist/docs/previews.md

@@ -29,11 +29,18 @@ The preview gets its own isolated database, buckets, and volumes; writing to the
 
 A volume clone is an exact replica of the parent's on-disk data — uploads, caches, database files, and search indexes alike. This needs no extra configuration: the service boots on the cloned data exactly as it would after a restart, and writes to the preview's copy never affect the parent.
 
+## Secrets and config
+
+A preview also inherits the parent environment's secrets and config values, so its services start with the same configuration the parent runs with — nothing to re-enter.
+
+To give previews a different value for a specific secret or config — say a sandbox API key or a test-only endpoint — set a **preview override** on the parent environment's Secrets and config page in the Specific Dashboard. Every preview branched from that environment then uses the override for that value while still inheriting everything else. Overrides are managed entirely from the dashboard.
+
 ---
 
 Related topics:
 
 - Run `specific docs volumes` for declaring persistent volumes
 - Run `specific docs services` for service configuration
+- Run `specific docs secrets-config` for setting preview secret and config overrides
 - Run `specific docs observability` for querying a preview's logs and metrics
 - Run `specific docs deployments` for debugging a failed preview deploy (`specific deployment show -e <preview>` prints the failure; add `--output` for the build log)

package/dist/docs/secrets-config.md

@@ -135,6 +135,12 @@ This file is automatically gitignored and not included in deployments. Productio
 
 In production, the user can update secrets and config values directly from the Specific Dashboard at https://dashboard.specific.dev — no `specific.hcl` change needed, but the new values only take effect on the next deployment. Point them there when they want to rotate a secret or change a config value in a deployed environment.
 
+## Preview environments
+
+Preview environments inherit their secrets and config values from the environment they branch from, so a preview starts with the parent's configuration without re-entering anything.
+
+To give previews a different value for a specific secret or config, set a **preview override** on the parent environment's Secrets and config page in the Specific Dashboard. Every preview branched from that environment then uses the override for that value while still inheriting the rest — handy for pointing previews at a sandbox API key or a test-only endpoint. Run `specific docs previews` for more on preview environments.
+
 ## Example
 
 ```hcl

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/cli",
-  "version": "0.1.183",
+  "version": "0.1.185",
   "description": "CLI for Specific infrastructure-as-code",
   "type": "module",
   "main": "dist/cli.js",