envstash-cli 0.9.0 → 0.11.0

package/README.md

@@ -46,6 +46,7 @@ envs sync
 | `push`    | Send local files to the cloud                        |
 | `sync`    | Reconcile both directions at once, keeping every key |
 | `remove`  | Delete files from the cloud (local copies stay)      |
+| `config`  | Show the settings in effect and where each came from |
 | `version` | Show the CLI version and its environment             |
 
 Run `envs help <command>` for details on any one of them.
@@ -243,7 +244,7 @@ on the dashboard under **Shared Files**, not inside any project.
 ```json
 {
   "project": "demo-app",
-  "files": [".env.local", ".env.production"]
+  "files": [".env", ".env.production"]
 }
 ```
 
@@ -253,10 +254,21 @@ files to track — and it is what lets a teammate clone the repo and run
 
 Without a link file the CLI guesses the project from your git remote's repo
 name and discovers `.env*` files in the repo root, plus files in `.config/`
-(see below). Dotenv files ending in `.example`, `.sample`, `.template`, and
+and `.agents/` (see below). That list is the default, and
+[`discover`](#settings) changes it. Dotenv files ending in `.example`, `.sample`, `.template`, and
 `.dist` are ignored, since those are meant to be committed and hold placeholder
 values.
 
+`.env.local` and `.env.*.local` are not discovered either. Every dotenv loader
+that layers files puts `.local` on top — `.env`, then `.env.<mode>`, then
+`.env.local`, then the real environment — so by name it is the override a
+developer writes to differ from the shared values on this one checkout. A tool
+that distributes the shared values fills the lower layers and leaves that one
+alone; syncing it would leave no layer that can differ between machines.
+`init`, `push`, and `sync` say when they skip one. To sync it anyway, list it in
+`.envstash.json` or name it on the command line — that is taken as written. A
+`.local` file already in the cloud keeps syncing until you `envs rm` it.
+
 ### Files in `.config/`
 
 A service-account key or a cert is a secret that is not `KEY=value`, and it does
@@ -287,8 +299,40 @@ than the one you are standing in.
 Outside a git repository, or if `git` is not installed, discovery adds nothing
 from `.config/` rather than guessing — over-discovery would upload a file nobody
 chose to share, while under-discovery just means listing it in `.envstash.json`
-by hand. The scan covers `.config/` and everything under it; files anywhere else
-are declared explicitly.
+by hand. The scan covers each discovered directory and everything under it;
+files anywhere else are declared explicitly.
+
+### Files in `.agents/`
+
+`.agents/` is where a repo keeps what its AI coding agents read — skills, rules,
+per-tool settings. When the directory exists it is discovered the same way as
+`.config/`, with two differences:
+
+- **Documents are kept.** Skills and rules are markdown, so the rule that keeps
+  a README out of `.config/` does not apply.
+- **It is never added to `.gitignore` for you.** Plenty of repos commit
+  `.agents/`, and ignoring it on the way past would make the next `git add -A`
+  silently leave it behind.
+
+Git-ignore is still the gate, so there are three cases:
+
+| `.agents/` is…                | What `push` and `sync` do                         |
+| ----------------------------- | ------------------------------------------------- |
+| git-ignored                   | Sync its files                                    |
+| committed                     | Nothing — git already carries it                  |
+| neither ignored nor committed | Nothing, and say so, so you can pick one of those |
+
+A `.agents` that is a symlink (to `.claude`, say) is skipped, like every other
+link.
+
+### Choosing what is discovered
+
+Discovery only decides the file list for a repo that has none of its own. Once
+`.envstash.json` lists `files`, that list is used as written — add
+`.agents/…` paths to it by hand, or remove `files` to go back to discovery.
+
+To change the defaults on this machine, set [`discover`](#settings). Run
+`envs config` to see the list in effect and the files it currently finds.
 
 Monorepos can track nested paths by listing them explicitly:
 
@@ -349,13 +393,31 @@ by hand. The file is optional; create it to change a default.
 
 ```json
 {
-  "confirmNewFiles": true
+  "confirmNewFiles": true,
+  "discover": [".env*", ".config", ".agents"]
 }
 ```
 
-| Setting           | Default | Purpose                                                                            |
-| ----------------- | ------- | ---------------------------------------------------------------------------------- |
-| `confirmNewFiles` | `false` | Ask before `push` or `sync` uploads a file that discovery found for the first time |
+- **`confirmNewFiles`** (default `false`) — ask before `push` or `sync` uploads
+  a file that discovery found for the first time.
+- **`discover`** (default `[".env*", ".config", ".agents"]`) — what is synced in
+  a repo that does not list its own files.
+
+`discover` **replaces** the default list, so leaving an entry out turns it off:
+`[".env*", ".config"]` stops syncing `.agents/`, and `[]` discovers nothing.
+`".env*"` means the dotenv files in the repo root. Any other entry is a
+directory inside the repo, whose git-ignored files are synced — add `".claude"`
+to carry local agent settings, for example. `.git`, `node_modules`, and paths
+that leave the repo are refused.
+
+It lives here rather than in `.envstash.json` on purpose: that file arrives
+with a clone, and a repo should not get to choose which of your directories are
+uploaded. Taking a directory out of `discover` stops new files being found; files
+already in the cloud keep syncing until you `envs rm` them.
+
+`envs config` prints every setting in effect and whether it came from this file
+or is a default, along with the server, account, and this repo's project and
+files. It never prints a token.
 
 With `confirmNewFiles` on, `push` and `sync` ask on a terminal, and anywhere
 else (CI, a pipe) they stop unless you pass `--yes` (`-y`). Files you named on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envstash-cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Git-style CLI for EnvStash — keep your .env files in sync with your cloud account.",
   "keywords": [
     "env",

package/src/commands/misc.mjs

@@ -1,19 +1,21 @@
-import { readFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { api } from '../api.mjs'
-import { configDir, getStoredEmail } from '../config.mjs'
+import { configDir, configPath, getStoredEmail, getToken } from '../config.mjs'
 import {
   discoverTrackedFiles,
   findRepoRoot,
+  LINK_FILE,
   readLink,
   resolveProject,
   writeLink,
 } from '../project.mjs'
 import { requireHostToken, resolveHostFor, resolveHostSource } from '../session.mjs'
+import { DEFAULT_SETTINGS, readSettings, settingsPath } from '../settings.mjs'
 import { out, pad, pluralize, sanitize, style } from '../ui.mjs'
-import { announceIgnoredSecretDir } from './push.mjs'
+import { announceDiscoveryDirs, announceLocalEnvFiles } from './push.mjs'
 
 /**
  * `envs version` — the version, and the environment it would act in.
@@ -76,6 +78,120 @@ function sourceLabel(source) {
   )
 }
 
+/**
+ * `envs config` — every setting in effect, and where each one came from.
+ *
+ * The CLI's behaviour is decided in four places — `settings.json`, the
+ * credential file, the environment, and the repo's link file — and none of them
+ * is on screen when a command does something unexpected. This prints the
+ * resolved answer from all four, read through the same functions the sync
+ * commands use, so it cannot describe a configuration they would not act on.
+ *
+ * Never the token: only whether there is one, and which place supplied it.
+ * Nothing here touches the network, so it works signed out and offline.
+ */
+export async function config(flags) {
+  const settings = readSettings()
+  const { host, source } = resolveHostSource(flags)
+  const repoRoot = findRepoRoot()
+  const link = readLink(repoRoot)
+  const project = resolveProject(repoRoot, flags.project)
+  const linked = Boolean(link?.files?.length)
+
+  const details = {
+    configDir: configDir(),
+    settingsFile: { path: settingsPath(), exists: existsSync(settingsPath()) },
+    settings,
+    // Which settings the file changed, so a default is never mistaken for a choice.
+    changed: Object.keys(settings).filter(
+      key => JSON.stringify(settings[key]) !== JSON.stringify(DEFAULT_SETTINGS[key])
+    ),
+    credentialsFile: { path: configPath(), exists: existsSync(configPath()) },
+    host,
+    hostSource: source,
+    account: getStoredEmail(host),
+    token: tokenSource(host, source),
+    repo: {
+      root: repoRoot,
+      linkFile: link ? LINK_FILE : null,
+      project: project.name,
+      projectSource: project.source,
+      files: linked ? link.files : discoverTrackedFiles(repoRoot, settings.discover),
+      filesSource: linked ? 'link' : 'discovery',
+    },
+  }
+
+  if (flags.json) {
+    out(JSON.stringify(details, null, 2))
+    return 0
+  }
+
+  const width = 18
+  const row = (label, value, note) =>
+    out(`  ${pad(label, width)}${value}${note ? style.dim(`  (${note})`) : ''}`)
+  const origin = key => (details.changed.includes(key) ? 'settings.json' : 'default')
+
+  out()
+  out(`  ${style.bold('Settings')} ${style.dim(details.settingsFile.path)}`)
+  if (!details.settingsFile.exists) {
+    out(`  ${style.dim('No settings file — every value below is a default.')}`)
+  }
+  out()
+  for (const [key, value] of Object.entries(settings)) {
+    row(key, Array.isArray(value) ? value.join(', ') || style.dim('nothing') : value, origin(key))
+  }
+
+  out()
+  out(`  ${style.bold('Server')}`)
+  out()
+  row('host', host, sourceLabel(source))
+  row('account', details.account ?? style.dim('not signed in'))
+  row('token', TOKEN_LABELS[details.token])
+  row('credentials', style.dim(details.credentialsFile.path))
+
+  out()
+  out(`  ${style.bold('This repo')} ${style.dim(repoRoot)}`)
+  out()
+  row('project', project.name, PROJECT_LABELS[project.source])
+  row('link file', link ? LINK_FILE : style.dim('none'))
+  row(
+    'files',
+    details.repo.files.length ? pluralize(details.repo.files.length, 'file') : style.dim('none'),
+    linked ? `listed in ${LINK_FILE}` : 'found by discovery'
+  )
+  for (const file of details.repo.files) {
+    out(`    ${style.dim('·')} ${file}`)
+  }
+  out()
+
+  return 0
+}
+
+/**
+ * Where this command's token would come from, without revealing it. Mirrors
+ * `requireHostToken`: the environment's token is not spent on a host the link
+ * file chose.
+ */
+function tokenSource(host, hostSource) {
+  if (hostSource !== 'link' && process.env.ENVSTASH_TOKEN) {
+    return 'env'
+  }
+
+  return getToken(host, { allowEnvToken: false }) ? 'stored' : 'none'
+}
+
+const TOKEN_LABELS = {
+  env: 'from ENVSTASH_TOKEN',
+  stored: 'stored on this machine',
+  none: 'none',
+}
+
+const PROJECT_LABELS = {
+  flag: 'from --project',
+  link: `from ${LINK_FILE}`,
+  guess: 'guessed from the repo name',
+}
+
 /** `envs whoami` — which account this machine is signed in as. */
 export async function whoami(flags) {
   const { host, token } = await requireHostToken(flags)
@@ -145,9 +261,12 @@ export async function init(flags, args) {
 
   // Before discovery, so a not-yet-ignored .config/ lands in the link file
   // this init writes rather than being silently absent from it.
-  announceIgnoredSecretDir(repoRoot)
+  announceDiscoveryDirs(repoRoot, { discovering: !existing?.files?.length })
 
-  const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
+  const files = existing?.files?.length
+    ? existing.files
+    : discoverTrackedFiles(repoRoot, readSettings().discover)
+  announceLocalEnvFiles(repoRoot, { discovering: !existing?.files?.length, covered: files })
   const path = writeLink(repoRoot, {
     project: name,
     files,
@@ -209,9 +328,12 @@ export async function link(flags, args) {
   await api.projectStatus(host, token, name)
 
   // Same moment as in init: discovery is about to decide the link file's list.
-  announceIgnoredSecretDir(repoRoot)
+  announceDiscoveryDirs(repoRoot, { discovering: !existing?.files?.length })
 
-  const files = existing?.files?.length ? existing.files : discoverTrackedFiles(repoRoot)
+  const files = existing?.files?.length
+    ? existing.files
+    : discoverTrackedFiles(repoRoot, readSettings().discover)
+  announceLocalEnvFiles(repoRoot, { discovering: !existing?.files?.length, covered: files })
   const path = writeLink(repoRoot, { project: name, files, host: existing?.host ?? null })
 
   out()

package/src/commands/push.mjs

@@ -9,23 +9,92 @@ import {
   resolveFileNames,
   SHARED_SCOPE,
 } from '../context.mjs'
-import { ensureSecretDirIgnored, SECRET_FILE_DIR } from '../project.mjs'
+import {
+  ensureSecretDirIgnored,
+  ENV_FILES_TARGET,
+  lacksIgnoreRule,
+  LINK_FILE,
+  localEnvFiles,
+  SECRET_FILE_DIR,
+} from '../project.mjs'
 import { resolveRepoFile } from '../repo-path.mjs'
 import { readSettings } from '../settings.mjs'
 import { compareProject, FILE_STATE } from '../status.mjs'
 import { CliError, confirm, isInteractive, out, pad, pluralize, style } from '../ui.mjs'
 
-/** Say that .gitignore was edited — quietly rewriting a user's file is worse. */
-export function announceIgnoredSecretDir(repoRoot) {
-  if (!ensureSecretDirIgnored(repoRoot)) {
+/**
+ * Get the discovered directories ready, and say what was done or left undone.
+ *
+ * Discovery only offers files git ignores, so a directory with contents that
+ * nothing tracks and nothing ignores is carried by neither git nor envstash.
+ * For `.config/` that is closed by adding the ignore rule — and saying so, since
+ * quietly rewriting a user's file is worse. For any other directory it is only
+ * pointed out: `.agents/` is committed in plenty of repos, and ignoring it on
+ * the way past would make the next `git add -A` silently leave it behind.
+ *
+ * A directory the developer took out of `discover` is not touched or mentioned.
+ * `discovering` is false when this run's files were chosen by name or by the
+ * link file: discovery is not deciding anything then, so there is nothing to
+ * point out.
+ */
+export function announceDiscoveryDirs(repoRoot, { discovering = true } = {}) {
+  const dirs = readSettings().discover.filter(target => target !== ENV_FILES_TARGET)
+
+  if (dirs.includes(SECRET_FILE_DIR) && ensureSecretDirIgnored(repoRoot)) {
+    out()
+    out(
+      `  ${style.green('+')} Added ${style.bold(`${SECRET_FILE_DIR}/`)} to .gitignore ` +
+        style.dim('— secrets sync through EnvStash, not git')
+    )
+  }
+
+  const leftToGit = discovering
+    ? dirs.filter(dir => dir !== SECRET_FILE_DIR && lacksIgnoreRule(repoRoot, dir))
+    : []
+
+  if (leftToGit.length > 0) {
+    out()
+  }
+
+  for (const dir of leftToGit) {
+    out(
+      `  ${style.yellow('!')} ${style.bold(`${dir}/`)} is not git-ignored, so it is not synced ` +
+        style.dim('— add it to .gitignore to sync it through EnvStash, or commit it')
+    )
+  }
+}
+
+/**
+ * Say which `.local` files the dotenv scan left behind, and how to list one.
+ *
+ * The scan skips them by name: `.local` is the per-checkout override layer, not
+ * the shared values. A developer whose secrets live in `.env.local` would
+ * otherwise see it silently missing from the list a command just decided.
+ *
+ * `covered` is that list. A `.local` file already in the cloud — pushed by an
+ * older version, or by name — is still synced through the cloud listing until
+ * `envs rm`, and saying otherwise would be false. Only when discovery decided
+ * the list (`discovering`) and the scan is on is there anything to point out.
+ */
+export function announceLocalEnvFiles(repoRoot, { discovering = true, covered = [] } = {}) {
+  if (!discovering || !readSettings().discover.includes(ENV_FILES_TARGET)) {
+    return
+  }
+
+  const left = localEnvFiles(repoRoot).filter(name => !covered.includes(name))
+
+  if (left.length === 0) {
     return
   }
 
   out()
-  out(
-    `  ${style.green('+')} Added ${style.bold(`${SECRET_FILE_DIR}/`)} to .gitignore ` +
-      style.dim('— secrets sync through EnvStash, not git')
-  )
+
+  for (const name of left) {
+    out(
+      `  ${style.dim('·')} ${style.bold(name)} is a local override, so it is not synced ` +
+        style.dim(`— list it in ${LINK_FILE} to sync it`)
+    )
+  }
 }
 
 /**
@@ -58,7 +127,9 @@ export async function push(flags, args) {
   // this very push rather than the next one. Not under --dry-run: a preview
   // that edits files is not a preview.
   if (!flags['dry-run']) {
-    announceIgnoredSecretDir(context.repoRoot)
+    announceDiscoveryDirs(context.repoRoot, {
+      discovering: args.length === 0 && !context.link?.files?.length,
+    })
   }
 
   const cloudFiles = await fetchCloudFiles(context, scope)
@@ -70,6 +141,11 @@ export async function push(flags, args) {
     requested: args,
   })
 
+  announceLocalEnvFiles(context.repoRoot, {
+    discovering: args.length === 0 && !context.link?.files?.length,
+    covered: names,
+  })
+
   const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const presentNames = names.filter(name => localFiles.get(name) !== null)
 
@@ -189,7 +265,8 @@ export async function push(flags, args) {
  * ones discovery found.
  *
  * Discovery sweeps root `.env*` files and everything git-ignored under
- * `.config/`, recursively, and used to upload the lot and only then list it.
+ * `.config/` and `.agents/`, recursively, and used to upload the lot and only
+ * then list it.
  * The list now always comes first, marking which files were discovered.
  *
  * Uploading them is the default: a developer who runs `envs push` in their own

package/src/commands/sync.mjs

@@ -15,7 +15,13 @@ import { resolveRepoFile } from '../repo-path.mjs'
 import { compareProject } from '../status.mjs'
 import { conflictExitCode, isBlocked, isChanging, planSync, PREFER, SYNC_ACTION } from '../sync.mjs'
 import { CliError, out, pad, pluralize, sanitize, style } from '../ui.mjs'
-import { announceIgnoredSecretDir, confirmNewFiles, fetchCloudFiles, pushOneBlob } from './push.mjs'
+import {
+  announceDiscoveryDirs,
+  announceLocalEnvFiles,
+  confirmNewFiles,
+  fetchCloudFiles,
+  pushOneBlob,
+} from './push.mjs'
 
 /**
  * `envs sync` — reconcile this repo with the cloud, in both directions at once.
@@ -53,7 +59,9 @@ export async function sync(flags, args) {
   // .config/ is covered by this run rather than the next one, and never under
   // --dry-run, because a preview that edits files is not a preview.
   if (!flags['dry-run']) {
-    announceIgnoredSecretDir(context.repoRoot)
+    announceDiscoveryDirs(context.repoRoot, {
+      discovering: args.length === 0 && !context.link?.files?.length,
+    })
   }
 
   const cloudFiles = await fetchCloudFiles(context, scope)
@@ -68,6 +76,11 @@ export async function sync(flags, args) {
     sink: 'write',
   })
 
+  announceLocalEnvFiles(context.repoRoot, {
+    discovering: args.length === 0 && !context.link?.files?.length,
+    covered: names,
+  })
+
   const localFiles = loadLocalFiles(context.repoRoot, names, cloudKinds(cloudFiles))
   const comparison = compareProject({
     cloudFiles: cloudFiles.filter(file => names.includes(file.name)),

package/src/context.mjs

@@ -5,6 +5,7 @@ import { parseEnvFile } from './env-file.mjs'
 import { discoverTrackedFiles, findRepoRoot, readLink, resolveProject } from './project.mjs'
 import { findSymlink, resolveInsideRepo, resolveRepoFile } from './repo-path.mjs'
 import { requireHostToken } from './session.mjs'
+import { readSettings } from './settings.mjs'
 import { errOut, pluralize, style } from './ui.mjs'
 
 /**
@@ -35,8 +36,9 @@ export async function resolveContext(flags) {
  * Explicit arguments win. Otherwise the link file's list is authoritative if
  * present — an explicit list is the only way to include a nested path like
  * `apps/web/.env.local`, which discovery does not scan for. With no link file,
- * fall back to the union of what discovery finds — root `.env*` files plus git-ignored
- * files in `.config/` — and whatever the cloud holds. Those inferred names skip
+ * fall back to the union of what discovery finds — by default root `.env*` files plus
+ * git-ignored files in `.config/` and `.agents/`; the `discover` setting says otherwise —
+ * and whatever the cloud holds. Those inferred names skip
  * symbolic links with a warning rather than refusing (see `skipSymlinks`);
  * `sink` is `'write'` for `pull`, so the warning says the file is not written.
  */
@@ -49,7 +51,10 @@ export function resolveFileNames({ repoRoot, link, cloudFiles, requested, sink =
     return check([...new Set(link.files)].sort())
   }
 
-  const names = new Set([...discoverTrackedFiles(repoRoot), ...cloudFiles.map(file => file.name)])
+  const names = new Set([
+    ...discoverTrackedFiles(repoRoot, readSettings().discover),
+    ...cloudFiles.map(file => file.name),
+  ])
 
   return skipSymlinks(repoRoot, check([...names].sort()), sink)
 }

package/src/index.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { abandonedConnection } from './api.mjs'
 import { diff } from './commands/diff.mjs'
 import { login, logout } from './commands/login.mjs'
-import { init, link, list, version as versionCommand, whoami } from './commands/misc.mjs'
+import { config, init, link, list, version as versionCommand, whoami } from './commands/misc.mjs'
 import { pull } from './commands/pull.mjs'
 import { push } from './commands/push.mjs'
 import { remove } from './commands/remove.mjs'
@@ -38,6 +38,7 @@ const HANDLERS = {
   push,
   sync,
   remove,
+  config,
   version: versionCommand,
 }
 
@@ -281,7 +282,7 @@ function printHelp(topic) {
   out(`    --host <url>       ${style.dim('Target another EnvStash server')}`)
   out(`    --port <n>         ${style.dim('Target a dev server on localhost at this port')}`)
   out(
-    `    --json             ${style.dim('Machine-readable output (status, list, whoami, version)')}`
+    `    --json             ${style.dim('Machine-readable output (status, list, whoami, config, version)')}`
   )
   out(
     `    --exit-zero        ${style.dim('Always exit 0, even when out of sync (status, diff, sync)')}`
@@ -433,6 +434,22 @@ const COMMAND_HELP = {
   link: ['Link this repo to a project that already exists.', '', '  envs link my-app'],
   list: ['List every project in your account.', '', '  envs list', '  envs list --json'],
   whoami: ['Show which account this machine is signed in as.', '', '  envs whoami'],
+  config: [
+    'Print every setting in effect and where each one came from: your',
+    '~/.envstash/settings.json, the server and account commands would use, and',
+    'this repo’s project and files. Tokens are never printed. Works offline.',
+    '',
+    'To change what is synced by default, set "discover" in settings.json. It',
+    'replaces the default list, so leave an entry out to turn it off:',
+    '',
+    '  { "discover": [".env*", ".config", ".agents"] }',
+    '',
+    '".env*" is the dotenv files in the repo root, minus templates and .local',
+    'overrides; anything else is a directory whose git-ignored files are synced.',
+    '',
+    '  envs config',
+    '  envs config --json',
+  ],
   version: [
     'Show the version, runtime, install path, and which server commands would',
     'talk to. --version and -v print the bare version for scripts.',

package/src/manifest.mjs

@@ -29,6 +29,7 @@ export const CLI_COMMANDS = [
   { name: 'push', summary: 'Send local files to the cloud' },
   { name: 'sync', summary: 'Reconcile both directions at once, keeping every key' },
   { name: 'remove', summary: 'Delete files from the cloud (local copies stay)', aliases: ['rm'] },
+  { name: 'config', summary: 'Show the settings in effect and where each came from' },
   { name: 'version', summary: 'Show the CLI version and its environment' },
 ]
 

package/src/project.mjs

@@ -57,6 +57,17 @@ function runGit(args, { cwd, input } = {}) {
  */
 const TEMPLATE_SUFFIXES = ['.example', '.sample', '.template', '.dist']
 
+/**
+ * The per-checkout override layer. Every dotenv loader that layers files agrees
+ * on the stack — `.env`, `.env.<mode>`, `.env.local`, `.env.<mode>.local`, then
+ * the real environment — and `.local` is, by name, what a developer writes to
+ * differ from the shared values on this one checkout. A tool that distributes
+ * the shared values fills the lower layers and leaves this one alone: syncing
+ * it would leave no layer that can differ between machines. Listing the file in
+ * the link file or naming it on the command line still syncs it.
+ */
+const LOCAL_SUFFIX = '.local'
+
 /**
  * Walk up from `startDir` looking for a repo root.
  *
@@ -165,13 +176,14 @@ export function guessProjectName(repoRoot) {
 }
 
 /**
- * Discover `.env*` files in the repo root.
+ * The dotenv files in the repo root that could hold a real value: `.env` and
+ * `.env.*`, minus templates and type declarations, regular files only.
  *
  * Deliberately not recursive: walking a whole tree would wander into
  * node_modules and vendored fixtures, and a monorepo's nested files are better
  * declared explicitly in the link file than guessed at.
  */
-export function discoverEnvFiles(repoRoot) {
+function rootEnvFiles(repoRoot) {
   let names
 
   try {
@@ -196,12 +208,45 @@ export function discoverEnvFiles(repoRoot) {
     .sort()
 }
 
+/** Discover `.env*` files in the repo root — the shared layers, not `.local`. */
+export function discoverEnvFiles(repoRoot) {
+  return rootEnvFiles(repoRoot).filter(name => !name.endsWith(LOCAL_SUFFIX))
+}
+
+/**
+ * The `.local` files discovery left behind, so a command can say why they are
+ * missing from a list it just decided.
+ */
+export function localEnvFiles(repoRoot) {
+  return rootEnvFiles(repoRoot).filter(name => name.endsWith(LOCAL_SUFFIX))
+}
+
 /**
  * Where credential *files* live, by convention: a service-account JSON, a cert, a
  * private key — the things that are secrets but are not `KEY=value`.
  */
 export const SECRET_FILE_DIR = '.config'
 
+/**
+ * Where a repo keeps what its AI coding agents read — skills, rules, per-tool
+ * settings. Not a credential, but the same population as one: files a developer
+ * needs on every machine and, when the repo ignores them, cannot get from git.
+ */
+export const AGENTS_DIR = '.agents'
+
+/**
+ * The discovery target that means "dotenv files in the repo root". Every other
+ * target names a directory; this one names the scan in `discoverEnvFiles`, which
+ * is a naming rule rather than a place.
+ */
+export const ENV_FILES_TARGET = '.env*'
+
+/**
+ * What discovery looks at when the developer has not said otherwise — the
+ * `discover` list in `~/.envstash/settings.json` replaces it wholesale.
+ */
+export const DEFAULT_DISCOVER = [ENV_FILES_TARGET, SECRET_FILE_DIR, AGENTS_DIR]
+
 /**
  * Which of `names` git ignores, as a Set.
  *
@@ -251,7 +296,9 @@ const DOCUMENT_SUFFIXES = [
 ]
 
 /**
- * Discover files in `.config/` — all of them, except documents.
+ * Discover the files in one directory that git ignores.
+ *
+ * `.config/` is where this started, and the reasoning below is written for it:
  *
  * The dotenv scan above cannot find these: they are not named `.env*` and they do
  * not live in the repo root. Before this existed, a project with a service-account
@@ -265,8 +312,12 @@ const DOCUMENT_SUFFIXES = [
  * a file is offered only when it is git-ignored, small enough to push, and has a
  * name the sync commands will accept.
  */
-export function discoverSecretFiles(repoRoot) {
-  const directory = join(repoRoot, SECRET_FILE_DIR)
+export function discoverDirFiles(repoRoot, dir) {
+  const directory = join(repoRoot, dir)
+  // Only `.config/` drops documents. There a README is noise beside the keys;
+  // in `.agents/` the markdown *is* the content, and a directory the developer
+  // listed themselves is taken at their word.
+  const skipDocuments = dir === SECRET_FILE_DIR
   let entries
 
   try {
@@ -277,15 +328,18 @@ export function discoverSecretFiles(repoRoot) {
 
   const candidates = entries
     // Nested entries come back joined with the platform separator; names are POSIX.
-    .map(entry => `${SECRET_FILE_DIR}/${entry.split(sep).join('/')}`)
-    .filter(name => !DOCUMENT_SUFFIXES.some(suffix => name.toLowerCase().endsWith(suffix)))
+    .map(entry => `${dir}/${entry.split(sep).join('/')}`)
+    .filter(
+      name =>
+        !skipDocuments || !DOCUMENT_SUFFIXES.some(suffix => name.toLowerCase().endsWith(suffix))
+    )
     // The grammar the server and `resolveInsideRepo` both enforce. Discovering a
     // name they would refuse produces a link file that cannot be pushed.
     .filter(name => isSafeRepoPath(name))
     .filter(name => {
       try {
-        // A link anywhere on the path — `.config` itself, a subdirectory, or the
-        // file — could point outside the repo, so it is not offered.
+        // A link anywhere on the path — the directory itself, a subdirectory, or
+        // the file — could point outside the repo, so it is not offered.
         if (findSymlink(repoRoot, name)) {
           return false
         }
@@ -304,26 +358,25 @@ export function discoverSecretFiles(repoRoot) {
   return candidates.filter(name => ignored.has(name)).sort()
 }
 
+/** Discover files in `.config/` — all of them, except documents. */
+export function discoverSecretFiles(repoRoot) {
+  return discoverDirFiles(repoRoot, SECRET_FILE_DIR)
+}
+
 /**
- * Make sure `.config/` is git-ignored before discovery asks about it.
- *
- * Being ignored is discovery's signal for "secret", which makes an unignored
- * `.config/` silently invisible to `envs push` — a real footgun: the developer
- * sees a directory full of credentials and a push that ignores them, with
- * nothing saying why. Rather than documenting that, push and init close it:
- * when the directory has contents, nothing in it is tracked by git, and it is
- * not already ignored, `.config/` is added to .gitignore. A `.config/` with
- * tracked files is a repo that commits configuration there on purpose, and is
- * left alone.
+ * True when `dir` has contents that neither git nor envstash will carry:
+ * nothing in it is tracked, and nothing ignores it.
  *
- * Returns true when .gitignore was changed — the caller must say so out loud,
- * because a CLI editing a file it does not own should never do it silently.
+ * Being ignored is discovery's signal, which makes a directory in this state
+ * silently invisible to `envs push`. What to do about it differs by directory —
+ * see `ensureSecretDirIgnored` and the note `push` prints for the others — but
+ * the question is the same one.
  */
-export function ensureSecretDirIgnored(repoRoot) {
+export function lacksIgnoreRule(repoRoot, dir) {
   let entries
 
   try {
-    entries = readdirSync(join(repoRoot, SECRET_FILE_DIR))
+    entries = readdirSync(join(repoRoot, dir))
   } catch {
     return false
   }
@@ -337,20 +390,40 @@ export function ensureSecretDirIgnored(repoRoot) {
   let tracked
 
   try {
-    tracked = runGit(['ls-files', '--', SECRET_FILE_DIR], { cwd: repoRoot }).trim()
+    tracked = runGit(['ls-files', '--', dir], { cwd: repoRoot }).trim()
   } catch {
     return false
   }
 
+  // Tracked content means the repo commits this directory on purpose.
   if (tracked !== '') {
     return false
   }
 
   // A synthetic name, so one question covers the directory: any rule broad
   // enough to ignore this probe ignores everything discovery would find.
-  const probe = `${SECRET_FILE_DIR}/envstash-ignore-probe`
+  const probe = `${dir}/envstash-ignore-probe`
 
-  if (gitIgnoredNames(repoRoot, [probe]).has(probe)) {
+  return !gitIgnoredNames(repoRoot, [probe]).has(probe)
+}
+
+/**
+ * Make sure `.config/` is git-ignored before discovery asks about it.
+ *
+ * Being ignored is discovery's signal for "secret", which makes an unignored
+ * `.config/` silently invisible to `envs push` — a real footgun: the developer
+ * sees a directory full of credentials and a push that ignores them, with
+ * nothing saying why. Rather than documenting that, push and init close it:
+ * when the directory has contents, nothing in it is tracked by git, and it is
+ * not already ignored, `.config/` is added to .gitignore. A `.config/` with
+ * tracked files is a repo that commits configuration there on purpose, and is
+ * left alone.
+ *
+ * Returns true when .gitignore was changed — the caller must say so out loud,
+ * because a CLI editing a file it does not own should never do it silently.
+ */
+export function ensureSecretDirIgnored(repoRoot) {
+  if (!lacksIgnoreRule(repoRoot, SECRET_FILE_DIR)) {
     return false
   }
 
@@ -379,9 +452,21 @@ export function ensureSecretDirIgnored(repoRoot) {
   return true
 }
 
-/** Everything auto-discovery offers to track: root dotenv files, then `.config/` files. */
-export function discoverTrackedFiles(repoRoot) {
-  return [...discoverEnvFiles(repoRoot), ...discoverSecretFiles(repoRoot)]
+/**
+ * Everything auto-discovery offers to track, target by target in the order
+ * given: root dotenv files for `.env*`, the git-ignored files of each directory
+ * otherwise.
+ *
+ * `targets` is passed in rather than read from settings here, so this stays a
+ * function of the repo alone; callers hand it `readSettings().discover`.
+ */
+export function discoverTrackedFiles(repoRoot, targets = DEFAULT_DISCOVER) {
+  const names = targets.flatMap(target =>
+    target === ENV_FILES_TARGET ? discoverEnvFiles(repoRoot) : discoverDirFiles(repoRoot, target)
+  )
+
+  // Two targets can overlap (`.config` and `.config/gcloud`); each file once.
+  return [...new Set(names)]
 }
 
 /**

package/src/settings.mjs

@@ -2,6 +2,8 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { configDir } from './config.mjs'
+import { DEFAULT_DISCOVER, ENV_FILES_TARGET } from './project.mjs'
+import { isSafeRepoPath } from './repo-path.mjs'
 import { CliError } from './ui.mjs'
 
 /**
@@ -11,15 +13,69 @@ import { CliError } from './ui.mjs'
  * stray comma signs the developer out of everything.
  *
  * Per machine rather than per repo: `.envstash.json` travels with a clone, and
- * how much a developer wants to be asked is theirs to decide, not the repo's.
+ * how much a developer wants to be asked — or which of their directories get
+ * swept up — is theirs to decide, not the repo's. A cloned repo that could say
+ * "also discover this directory" would be choosing what leaves the machine.
  *
  * {
- *   "confirmNewFiles": true
+ *   "confirmNewFiles": true,
+ *   "discover": [".env*", ".config"]
  * }
  */
-const DEFAULTS = {
+export const DEFAULT_SETTINGS = Object.freeze({
   /** Ask before uploading a file that discovery found for the first time. */
   confirmNewFiles: false,
+  /**
+   * What discovery looks at in a repo with no file list of its own: `.env*` for
+   * root dotenv files, and directories whose git-ignored files are offered.
+   * Replaces the default list rather than adding to it, so leaving an entry out
+   * is how it is turned off.
+   */
+  discover: Object.freeze([...DEFAULT_DISCOVER]),
+})
+
+/**
+ * One reader per setting: takes the value from the file and returns the value
+ * to use, or calls `refuse` — which throws — with what the value must be and a
+ * hint. A value of the
+ * wrong type is refused rather than coerced: `"false"` is a truthy string, and
+ * reading it as "yes, ask me" or as "no, don't" would both be a guess about a
+ * safety preference.
+ */
+const READERS = {
+  confirmNewFiles(value, refuse) {
+    if (typeof value !== 'boolean') {
+      refuse('must be true or false', 'Example: { "confirmNewFiles": true }')
+    }
+
+    return value
+  },
+
+  discover(value, refuse) {
+    const example = `Example: { "discover": ${JSON.stringify(DEFAULT_DISCOVER)} }`
+
+    if (!Array.isArray(value)) {
+      refuse('must be a list', example)
+    }
+
+    const targets = value.map(entry => {
+      // `.agents/` and `.agents` are the same directory to anyone typing it.
+      const target = typeof entry === 'string' ? entry.replace(/\/+$/, '') : entry
+
+      // The same grammar every synced name passes, which also keeps `.git`,
+      // `node_modules`, `..` and absolute paths out of the sweep.
+      if (target !== ENV_FILES_TARGET && !isSafeRepoPath(target)) {
+        refuse(
+          `lists ${JSON.stringify(entry)}, which is not something envstash can discover`,
+          `Use "${ENV_FILES_TARGET}" for root dotenv files, or a directory inside the repo. ${example}`
+        )
+      }
+
+      return target
+    })
+
+    return [...new Set(targets)]
+  },
 }
 
 export function settingsPath() {
@@ -29,16 +85,13 @@ export function settingsPath() {
 /**
  * The settings, with defaults for whatever the file does not say — or for a
  * file that is not there, which is the normal case.
- *
- * A value of the wrong type is refused rather than coerced: `"false"` is a
- * truthy string, and reading it as "yes, ask me" or as "no, don't" would both
- * be a guess about a safety preference.
  */
 export function readSettings() {
   const path = settingsPath()
+  const settings = { ...DEFAULT_SETTINGS, discover: [...DEFAULT_SETTINGS.discover] }
 
   if (!existsSync(path)) {
-    return { ...DEFAULTS }
+    return settings
   }
 
   let parsed
@@ -57,21 +110,14 @@ export function readSettings() {
     })
   }
 
-  const settings = { ...DEFAULTS }
-
-  for (const [key, fallback] of Object.entries(DEFAULTS)) {
+  for (const [key, read] of Object.entries(READERS)) {
     if (!(key in parsed)) {
       continue
     }
 
-    if (typeof parsed[key] !== typeof fallback) {
-      throw new CliError(
-        `"${key}" in ${path} must be ${typeof fallback === 'boolean' ? 'true or false' : `a ${typeof fallback}`}.`,
-        { hint: `Example: { "${key}": ${JSON.stringify(!fallback)} }` }
-      )
-    }
-
-    settings[key] = parsed[key]
+    settings[key] = read(parsed[key], (must, hint) => {
+      throw new CliError(`"${key}" in ${path} ${must}.`, { hint })
+    })
   }
 
   return settings