From 1ef8672badcc75c0b31d8a69bac39e6e986323ba Mon Sep 17 00:00:00 2001
From: YJack0000 <jack@pathors.com>
Date: Tue, 8 Sep 2026 00:23:13 +0800
Subject: [PATCH 1/3] [feature] key vault: env name on every entry, validated
 as UPPER_SNAKE_CASE, with a shared filter

---
 crates/patchbay-cli/src/keys.rs              |   1 +
 crates/patchbay-core/src/keys.rs             | 328 +++++++++++++++++++
 crates/patchbay-core/src/keys_verify.rs      |   1 +
 crates/patchbay-core/src/lib.rs              |   2 +-
 crates/patchbay-core/src/migrate/export.rs   |   1 +
 crates/patchbay-core/src/migrate/manifest.rs |   7 +
 crates/patchbay-core/src/migrate/setup.rs    |   1 +
 crates/patchbay-mcp/src/keys.rs              |   3 +
 8 files changed, 343 insertions(+), 1 deletion(-)

diff --git a/crates/patchbay-cli/src/keys.rs b/crates/patchbay-cli/src/keys.rs
index 7579d0b..5cfe96b 100644
--- a/crates/patchbay-cli/src/keys.rs
+++ b/crates/patchbay-cli/src/keys.rs
@@ -523,6 +523,7 @@ mod tests {
             last4: "1234".into(),
             source: "cli".into(),
             endpoint: None,
+            env: None,
         }
     }
 
diff --git a/crates/patchbay-core/src/keys.rs b/crates/patchbay-core/src/keys.rs
index dd12f5c..92bb333 100644
--- a/crates/patchbay-core/src/keys.rs
+++ b/crates/patchbay-core/src/keys.rs
@@ -151,6 +151,20 @@ pub struct KeyEntry {
     /// `keys.json` written before this field existed keeps parsing.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub endpoint: Option<String>,
+    /// The environment variable this key is conventionally exposed as —
+    /// `CLOUDFLARE_API_TOKEN`, `NEON_API_KEY` — in the shape
+    /// [`validate_env_name`] enforces. This is the name code, CI secrets and
+    /// vendor SDKs already read, and it is what lets a consumer that needs
+    /// `CLOUDFLARE_API_TOKEN` find `cf-gh-actions-deploy` without guessing:
+    /// `pb key run` injects the value under it, and an agent resolves a
+    /// required variable to a vault entry through it.
+    ///
+    /// Optional, because a key registered before the field existed has none,
+    /// and because not every entry is a variable (an issuer id, a D-U-N-S
+    /// number). Two entries may share one name — a dev and a production key
+    /// for the same service — and a lookup returns both.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub env: Option<String>,
 }
 
 impl KeyEntry {
@@ -207,6 +221,8 @@ pub struct NewKey {
     pub source: String,
     /// Instance URL, for providers that have more than one address.
     pub endpoint: Option<String>,
+    /// The variable name the key is exposed as; see [`KeyEntry::env`].
+    pub env: Option<String>,
 }
 
 impl NewKey {
@@ -223,6 +239,7 @@ impl NewKey {
             expires_at: None,
             source: source.into(),
             endpoint: None,
+            env: None,
         }
     }
 
@@ -257,6 +274,13 @@ impl NewKey {
         self.endpoint = endpoint.map(|e| normalize_endpoint(&e));
         self
     }
+
+    /// The variable name, trimmed. Validated by [`KeyRegistry::add`], not
+    /// here, so a bad name is reported next to the other registration errors.
+    pub fn env(mut self, env: Option<String>) -> Self {
+        self.env = env.map(|e| e.trim().to_string()).filter(|e| !e.is_empty());
+        self
+    }
 }
 
 /// Trim trailing slashes and surrounding whitespace so an endpoint can be
@@ -275,6 +299,8 @@ pub struct KeyPatch {
     pub scopes: Option<Vec<String>>,
     pub expires_at: Option<Option<DateTime<Utc>>>,
     pub endpoint: Option<Option<String>>,
+    /// `Some(Some(name))` sets the variable name, `Some(None)` clears it.
+    pub env: Option<Option<String>>,
 }
 
 impl KeyPatch {
@@ -285,6 +311,7 @@ impl KeyPatch {
             && self.scopes.is_none()
             && self.expires_at.is_none()
             && self.endpoint.is_none()
+            && self.env.is_none()
     }
 }
 
@@ -394,6 +421,9 @@ impl KeyRegistry {
     /// date of the rotation).
     pub fn add(&self, new: NewKey, secret: &str, overwrite: bool) -> anyhow::Result<KeyEntry> {
         validate_id(&new.id)?;
+        if let Some(env) = &new.env {
+            validate_env_name(env)?;
+        }
         if secret.is_empty() {
             anyhow::bail!("refusing to register `{}` with an empty secret", new.id);
         }
@@ -420,6 +450,7 @@ impl KeyRegistry {
             last4: last4(secret),
             source: new.source,
             endpoint: new.endpoint.as_deref().map(normalize_endpoint),
+            env: new.env,
         };
 
         match existing {
@@ -480,6 +511,13 @@ impl KeyRegistry {
         if let Some(endpoint) = patch.endpoint {
             entry.endpoint = endpoint.as_deref().map(normalize_endpoint);
         }
+        if let Some(env) = patch.env {
+            let env = env.map(|e| e.trim().to_string()).filter(|e| !e.is_empty());
+            if let Some(name) = &env {
+                validate_env_name(name)?;
+            }
+            entry.env = env;
+        }
         let updated = entry.clone();
         self.save(&file)?;
         Ok(updated)
@@ -629,6 +667,111 @@ pub fn expiring_within_at(entries: &[KeyEntry], now: DateTime<Utc>, days: i64) -
     hits
 }
 
+/// Upper bound on a variable name. The same as an id's: long enough for any
+/// real `NEXT_PUBLIC_…` name, short enough to keep a table readable.
+const MAX_ENV_NAME_LEN: usize = 64;
+
+/// The shape of a [`KeyEntry::env`] name: `UPPER_SNAKE_CASE`, starting with a
+/// letter — `CLOUDFLARE_API_TOKEN`, not `cloudflare_api_token`, not
+/// `CF-TOKEN`, not `1PASSWORD_TOKEN`.
+///
+/// Stricter than what a POSIX shell can export (the env vault's rule, which
+/// also allows lowercase) on purpose. The point of the field is that two
+/// people — or a person and an agent — spell the same variable the same way
+/// without coordinating, and one shape is the only thing that makes that
+/// true. The error suggests the corrected spelling where there is one.
+pub fn validate_env_name(name: &str) -> anyhow::Result<()> {
+    if name.is_empty() {
+        anyhow::bail!("env name cannot be empty");
+    }
+    if name.len() > MAX_ENV_NAME_LEN {
+        anyhow::bail!("env name `{name}` is longer than {MAX_ENV_NAME_LEN} characters");
+    }
+    let suggested: String = name
+        .chars()
+        .map(|c| match c {
+            '-' | ' ' | '.' => '_',
+            c => c.to_ascii_uppercase(),
+        })
+        .collect();
+    if name.chars().any(|c| c.is_ascii_lowercase()) {
+        anyhow::bail!(
+            "env names are UPPER_SNAKE_CASE (the shape code reads them in); try `{suggested}`"
+        );
+    }
+    if let Some(bad) = name
+        .chars()
+        .find(|c| !(c.is_ascii_uppercase() || c.is_ascii_digit() || *c == '_'))
+    {
+        anyhow::bail!(
+            "env name `{name}` contains `{bad}`; use A-Z, digits and `_` only, like `{suggested}`"
+        );
+    }
+    if !name.starts_with(|c: char| c.is_ascii_uppercase()) {
+        anyhow::bail!("env name `{name}` must start with a letter, like `CLOUDFLARE_API_TOKEN`");
+    }
+    Ok(())
+}
+
+/// The questions a caller narrows a listing by. All optional, all ANDed; a
+/// default filter matches everything.
+#[derive(Debug, Clone, Default)]
+pub struct KeyFilter {
+    /// Provider, compared case-insensitively.
+    pub provider: Option<String>,
+    /// Exact variable name ([`KeyEntry::env`]), compared case-insensitively so
+    /// a caller may ask for `cloudflare_api_token` and still find the entry.
+    pub env: Option<String>,
+    /// Free text, matched case-insensitively against id, label, purpose,
+    /// provider and env name.
+    pub query: Option<String>,
+}
+
+impl KeyFilter {
+    pub fn is_empty(&self) -> bool {
+        self.provider.is_none() && self.env.is_none() && self.query.is_none()
+    }
+
+    pub fn matches(&self, entry: &KeyEntry) -> bool {
+        let eq = |want: &Option<String>, have: Option<&str>| match want {
+            None => true,
+            Some(w) => have.is_some_and(|h| h.eq_ignore_ascii_case(w.trim())),
+        };
+        if !eq(&self.provider, Some(&entry.provider)) {
+            return false;
+        }
+        if !eq(&self.env, entry.env.as_deref()) {
+            return false;
+        }
+        match self.query.as_deref().map(str::trim).filter(|q| !q.is_empty()) {
+            None => true,
+            Some(q) => {
+                let q = q.to_lowercase();
+                [
+                    Some(entry.id.as_str()),
+                    Some(entry.label.as_str()),
+                    Some(entry.provider.as_str()),
+                    entry.purpose.as_deref(),
+                    entry.env.as_deref(),
+                ]
+                .into_iter()
+                .flatten()
+                .any(|field| field.to_lowercase().contains(&q))
+            }
+        }
+    }
+}
+
+/// The entries a filter keeps, in registry order. Pure, so the CLI, the MCP
+/// server and the panel narrow a listing by one rule.
+pub fn filter_keys(entries: &[KeyEntry], filter: &KeyFilter) -> Vec<KeyEntry> {
+    entries
+        .iter()
+        .filter(|e| filter.matches(e))
+        .cloned()
+        .collect()
+}
+
 /// Ids are lowercase slugs. Beyond keeping the board readable, this is what
 /// keeps an id from being mistaken for an option when it is handed to
 /// `security` as an argument.
@@ -963,6 +1106,7 @@ mod tests {
             last4: "0000".into(),
             source: "cli".into(),
             endpoint: None,
+            env: None,
         };
 
         let entries = vec![
@@ -1000,6 +1144,7 @@ mod tests {
             last4: "0000".into(),
             source: "cli".into(),
             endpoint: None,
+            env: None,
         };
         assert!(e.time_to_expiry(now).is_none());
         assert!(!e.is_expired(now));
@@ -1203,6 +1348,7 @@ mod tests {
             last4: "1234".into(),
             source: "cli".into(),
             endpoint: None,
+            env: None,
         };
 
         assert_eq!(with(None).expiry_state(now), KeyExpiryState::NoExpiry);
@@ -1363,4 +1509,186 @@ mod tests {
         );
         assert_eq!(entries[0].expires_at, Some(expires));
     }
+
+    #[test]
+    fn test_env_names_are_upper_snake_and_the_error_suggests_the_fix() {
+        assert!(validate_env_name("CLOUDFLARE_API_TOKEN").is_ok());
+        assert!(validate_env_name("NEXT_PUBLIC_GA4_ID").is_ok());
+        assert!(validate_env_name("A").is_ok());
+
+        let err = validate_env_name("cloudflare-api-token").unwrap_err().to_string();
+        assert!(err.contains("UPPER_SNAKE_CASE"), "{err}");
+        assert!(err.contains("`CLOUDFLARE_API_TOKEN`"), "{err}");
+
+        let err = validate_env_name("CF-TOKEN").unwrap_err().to_string();
+        assert!(err.contains("`-`"), "{err}");
+        assert!(err.contains("`CF_TOKEN`"), "{err}");
+
+        let err = validate_env_name("_TOKEN").unwrap_err().to_string();
+        assert!(err.contains("start with a letter"), "{err}");
+        let err = validate_env_name("1PASSWORD").unwrap_err().to_string();
+        assert!(err.contains("start with a letter"), "{err}");
+
+        assert!(validate_env_name("").is_err());
+        assert!(validate_env_name(&"A".repeat(65)).is_err());
+    }
+
+    #[test]
+    fn test_add_stores_a_valid_env_name_and_rejects_a_bad_one_before_writing() {
+        let v = vault();
+        let entry = v
+            .registry
+            .add(
+                sample("cf-api").env(Some(" CLOUDFLARE_API_TOKEN ".into())),
+                "secret-value",
+                false,
+            )
+            .unwrap();
+        assert_eq!(entry.env.as_deref(), Some("CLOUDFLARE_API_TOKEN"));
+
+        let err = v
+            .registry
+            .add(sample("bad").env(Some("bad name".into())), "x", false)
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("UPPER_SNAKE_CASE"), "{err}");
+        assert!(v.registry.get("bad").unwrap().is_none());
+        assert!(v.store.get("bad").unwrap().is_none());
+
+        // A blank name is no name, not an error.
+        let entry = v
+            .registry
+            .add(sample("blank").env(Some("  ".into())), "x", false)
+            .unwrap();
+        assert_eq!(entry.env, None);
+    }
+
+    #[test]
+    fn test_patch_sets_validates_and_clears_the_env_name() {
+        let v = vault();
+        v.registry.add(sample("cf-api"), "secret", false).unwrap();
+
+        let patch = KeyPatch {
+            env: Some(Some("CLOUDFLARE_API_TOKEN".into())),
+            ..Default::default()
+        };
+        assert!(!patch.is_empty());
+        let updated = v.registry.update_metadata("cf-api", patch).unwrap();
+        assert_eq!(updated.env.as_deref(), Some("CLOUDFLARE_API_TOKEN"));
+
+        let err = v
+            .registry
+            .update_metadata(
+                "cf-api",
+                KeyPatch {
+                    env: Some(Some("nope".into())),
+                    ..Default::default()
+                },
+            )
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("`NOPE`"), "{err}");
+        // A refused patch leaves the previous name in place.
+        assert_eq!(
+            v.registry.get("cf-api").unwrap().unwrap().env.as_deref(),
+            Some("CLOUDFLARE_API_TOKEN")
+        );
+
+        let cleared = v
+            .registry
+            .update_metadata(
+                "cf-api",
+                KeyPatch {
+                    env: Some(None),
+                    ..Default::default()
+                },
+            )
+            .unwrap();
+        assert_eq!(cleared.env, None);
+    }
+
+    #[test]
+    fn test_an_entry_without_env_reads_back_and_writes_no_env_field() {
+        let v = vault();
+        v.registry.add(sample("cf-api"), "secret", false).unwrap();
+        let raw = std::fs::read_to_string(v.registry.path()).unwrap();
+        assert!(!raw.contains("\"env\""), "{raw}");
+        // keys.json written before the field existed parses the same way.
+        assert_eq!(v.registry.get("cf-api").unwrap().unwrap().env, None);
+    }
+
+    #[test]
+    fn test_filter_narrows_by_provider_env_and_free_text() {
+        let now = Utc::now();
+        let entry = |id: &str, provider: &str, env: Option<&str>, purpose: &str| KeyEntry {
+            id: id.into(),
+            provider: provider.into(),
+            label: id.replace('-', " "),
+            purpose: Some(purpose.into()),
+            scopes: vec![],
+            created_at: now,
+            expires_at: None,
+            last4: "0000".into(),
+            source: "cli".into(),
+            endpoint: None,
+            env: env.map(Into::into),
+        };
+        let entries = vec![
+            entry("cf-deploy", "cloudflare", Some("CLOUDFLARE_API_TOKEN"), "deploy workers"),
+            entry("cf-r2", "Cloudflare", Some("R2_SECRET_ACCESS_KEY"), "R2 uploads"),
+            entry("neon-ci", "neon", Some("NEON_API_KEY"), "control plane for peregrine"),
+            entry("duns", "dnb", None, "not a secret, an index entry"),
+        ];
+        let ids = |f: KeyFilter| -> Vec<String> {
+            filter_keys(&entries, &f).into_iter().map(|e| e.id).collect()
+        };
+
+        assert!(KeyFilter::default().is_empty());
+        assert_eq!(ids(KeyFilter::default()).len(), 4);
+        assert_eq!(
+            ids(KeyFilter {
+                provider: Some("CLOUDFLARE".into()),
+                ..Default::default()
+            }),
+            vec!["cf-deploy", "cf-r2"]
+        );
+        // env is exact but case-insensitive: an agent asking in lowercase still finds it.
+        assert_eq!(
+            ids(KeyFilter {
+                env: Some("neon_api_key".into()),
+                ..Default::default()
+            }),
+            vec!["neon-ci"]
+        );
+        assert_eq!(
+            ids(KeyFilter {
+                query: Some("peregrine".into()),
+                ..Default::default()
+            }),
+            vec!["neon-ci"]
+        );
+        assert_eq!(
+            ids(KeyFilter {
+                query: Some("r2".into()),
+                ..Default::default()
+            }),
+            vec!["cf-r2"]
+        );
+        // Filters AND together.
+        assert!(ids(KeyFilter {
+            provider: Some("neon".into()),
+            query: Some("workers".into()),
+            ..Default::default()
+        })
+        .is_empty());
+        // A blank query matches everything rather than nothing.
+        assert_eq!(
+            ids(KeyFilter {
+                query: Some("  ".into()),
+                ..Default::default()
+            })
+            .len(),
+            4
+        );
+    }
 }
diff --git a/crates/patchbay-core/src/keys_verify.rs b/crates/patchbay-core/src/keys_verify.rs
index 582bb57..02aac75 100644
--- a/crates/patchbay-core/src/keys_verify.rs
+++ b/crates/patchbay-core/src/keys_verify.rs
@@ -653,6 +653,7 @@ mod tests {
             last4: "1234".into(),
             source: "cli".into(),
             endpoint: None,
+            env: None,
         }
     }
 
diff --git a/crates/patchbay-core/src/lib.rs b/crates/patchbay-core/src/lib.rs
index 11ad9ad..de766a5 100644
--- a/crates/patchbay-core/src/lib.rs
+++ b/crates/patchbay-core/src/lib.rs
@@ -57,7 +57,7 @@ pub use envs::{
     Attachment, EnvLayer, EnvMeta, EnvRegistry, EnvVarInfo, EnvVarSource, MergedEnv, ProjectEntry,
     SyncConfig,
 };
-pub use keys::{KeyEntry, KeyExpiryState, KeyPatch, KeyRegistry, NewKey};
+pub use keys::{filter_keys, validate_env_name, KeyEntry, KeyExpiryState, KeyFilter, KeyPatch, KeyRegistry, NewKey};
 pub use keys_verify::{verify_key, KeyVerifyOutcome, KeyVerifyStatus};
 pub use keystore::Keystore;
 pub use mcp_clients::{
diff --git a/crates/patchbay-core/src/migrate/export.rs b/crates/patchbay-core/src/migrate/export.rs
index 0555cc8..30ac553 100644
--- a/crates/patchbay-core/src/migrate/export.rs
+++ b/crates/patchbay-core/src/migrate/export.rs
@@ -415,6 +415,7 @@ impl Exporter<'_> {
                 purpose: entry.purpose,
                 scopes: entry.scopes,
                 expires_at: entry.expires_at,
+                env: entry.env,
                 last4: entry.last4,
                 included,
             });
diff --git a/crates/patchbay-core/src/migrate/manifest.rs b/crates/patchbay-core/src/migrate/manifest.rs
index 1f3cbd2..c173b39 100644
--- a/crates/patchbay-core/src/migrate/manifest.rs
+++ b/crates/patchbay-core/src/migrate/manifest.rs
@@ -154,6 +154,12 @@ pub struct KeyRecord {
     pub scopes: Vec<String>,
     #[serde(default)]
     pub expires_at: Option<DateTime<Utc>>,
+    /// The variable name the key is exposed as (`CLOUDFLARE_API_TOKEN`), when
+    /// the vault knows it. A name, not a value — it belongs in the readable
+    /// half, and it is what lets a new machine's setup say which variable each
+    /// missing key was.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub env: Option<String>,
     /// Last 4 characters, exactly as the vault stores them.
     pub last4: String,
     pub included: bool,
@@ -344,6 +350,7 @@ mod tests {
                 purpose: Some("deploy from CI".into()),
                 scopes: vec!["workers:edit".into()],
                 expires_at: None,
+                env: None,
                 last4: "9876".into(),
                 included: false,
             }],
diff --git a/crates/patchbay-core/src/migrate/setup.rs b/crates/patchbay-core/src/migrate/setup.rs
index b624ce7..b1759b6 100644
--- a/crates/patchbay-core/src/migrate/setup.rs
+++ b/crates/patchbay-core/src/migrate/setup.rs
@@ -257,6 +257,7 @@ mod tests {
                 purpose: None,
                 scopes: vec![],
                 expires_at: None,
+                env: None,
                 last4: "9876".into(),
                 included: false,
             }],
diff --git a/crates/patchbay-mcp/src/keys.rs b/crates/patchbay-mcp/src/keys.rs
index c30ca76..4c4e04d 100644
--- a/crates/patchbay-mcp/src/keys.rs
+++ b/crates/patchbay-mcp/src/keys.rs
@@ -425,6 +425,7 @@ mod tests {
             last4: "1234".into(),
             source: "mcp:test".into(),
             endpoint: None,
+            env: None,
         };
         let state = |e: KeyEntry| {
             describe(&e, now).unwrap()["expiry_state"]
@@ -462,6 +463,7 @@ mod tests {
             last4: "1234".into(),
             source: "mcp:test".into(),
             endpoint: None,
+            env: None,
         };
         assert_eq!(
             describe(&entry("cloudflare"), now).unwrap()["linked_tool"],
@@ -532,6 +534,7 @@ mod tests {
             last4: "1234".into(),
             source: "mcp:test".into(),
             endpoint: None,
+            env: None,
         };
         let value = describe(&entry, now).unwrap();
         let map = value.as_object().unwrap();

From 5ac2b4ddbb62052e93ba68621bc025570a539fa5 Mon Sep 17 00:00:00 2001
From: YJack0000 <jack@pathors.com>
Date: Tue, 8 Sep 2026 00:33:56 +0800
Subject: [PATCH 2/3] [feature] key vault: env names, pb key run/edit,
 resolve_env_vars, and MCP rules that make an agent look here first

---
 CHANGELOG.md                      | 105 ++++
 README.md                         |   5 +-
 app/src-tauri/src/lib.rs          |   7 +-
 app/src/components/KeysView.tsx   |  27 +-
 app/src/types.ts                  |  13 +
 crates/patchbay-cli/src/keys.rs   | 651 +++++++++++++++++++-
 crates/patchbay-core/src/keys.rs  |  37 +-
 crates/patchbay-core/src/lib.rs   |   5 +-
 crates/patchbay-mcp/src/keys.rs   | 975 +++++++++++++++++++++++++++++-
 crates/patchbay-mcp/src/server.rs |  79 ++-
 docs/env-vault.md                 |  15 +
 docs/key-vault.md                 | 164 ++++-
 12 files changed, 2020 insertions(+), 63 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96c33db..ad1e857 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,111 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-09-08
+
+### Added
+
+- **The vault is now something an agent looks in.** Sixty-five keys were in it,
+  and the agent working in your repo still asked *you* for
+  `CLOUDFLARE_API_TOKEN` — or wrote `<your-token-here>` and moved on, or
+  reported the variable as missing. Nothing refused it. It never looked, and
+  two things made that the rational move. A key was named only by slug
+  (`cf-gh-actions-deploy`), so the name code actually reads had no path to the
+  entry that holds it; the mapping existed as prose inside a `--purpose`
+  string, which is not an index. And an agent that did look dead-ended anyway,
+  because `get_key` is gated and there was no way to *use* a key without
+  reading it. A vault you cannot search and cannot spend gets worked around.
+
+  So keys have a second name. `KeyEntry.env` is the environment variable the
+  key is exposed as — `CLOUDFLARE_API_TOKEN`, `NEON_API_KEY` — validated as
+  UPPER_SNAKE_CASE (A–Z, digits, `_`, starting with a letter, at most 64
+  characters), which is the shape a shell and every dotenv parser accept. A
+  refusal spells the corrected name rather than restating the rule, so
+  `cf-token` comes back with "try `CF_TOKEN`" and the fix is a copy-paste. It
+  is optional on purpose: an Apple issuer id or a D-U-N-S number belongs in the
+  vault as something you would otherwise go hunting for, but it is not a
+  variable any program reads and inventing a name for it would be inventing a
+  fact. Two entries may share a name — a dev and a production
+  `LANGFUSE_SECRET_KEY` are two secrets under one identifier, which is the
+  normal shape — so nothing refuses it and a lookup returns both. A `keys.json`
+  written before the field existed parses unchanged, and the field is omitted
+  from the JSON when unset.
+
+  The convention the docs now state, because a name only helps if it is the
+  name the other end already uses: **use the name code already reads.** If the
+  repo, the CI secret or the vendor's SDK spells it `CLOUDFLARE_API_TOKEN`,
+  that is the name; patchbay's job is to be findable by what exists, not to
+  impose a taxonomy on it. Only when nothing has named it yet do you compose
+  one as `<PROVIDER>_<THING>_<KIND>` — `NEON_API_KEY`, `APPLE_ASC_ISSUER_ID`,
+  `GITHUB_APP_PRIVATE_KEY`, `R2_SECRET_ACCESS_KEY` — with the kind drawn from
+  `_API_KEY`, `_API_TOKEN`, `_SECRET`, `_SECRET_KEY`, `_PRIVATE_KEY`,
+  `_PASSWORD`, `_ID`, `_URL`. The `id` stays the lowercase slug and stays what
+  you type in a command; `env` is what everything else searches by.
+
+- **`pb key run <id>... -- <cmd>` — spend a key without reading it.** The only
+  way a value came out of the vault was `pb key copy`, which goes to the
+  clipboard: right for a human with a browser tab open, useless to a process,
+  and not something an agent should be doing at all. `run` resolves each id,
+  takes the value from the keychain, and starts the command with those
+  variables added to the environment it inherits. The value goes keychain →
+  child and touches nothing else — not stdout, not a log, not argv, not a file,
+  and not the context of whatever model asked for it. stderr names the
+  variables and the ids they came from, so you can see *what* was injected
+  without seeing what was injected. `--as NAME=<id>` covers the case where this
+  program wants a different name than the entry's, and an id with no `env` and
+  no `--as` is refused by name with the `pb key edit … --env` that fixes it,
+  because a run that silently dropped a credential fails somewhere much less
+  obvious. This is the second way a value leaves the vault, and the split is
+  deliberate: `copy` for the human, `run` for everything else.
+
+- **`pb key edit <id>` — metadata, and only metadata.** Every key registered
+  before this release has no `env` name, and a vault is worth the fraction of
+  it that is findable, so backfilling had to be one command that is obviously
+  safe to run. `edit` never opens the keychain and cannot rotate anything:
+  `--env NAME` / `--no-env`, plus `--provider`, `--label`, `--purpose`,
+  `--scopes`, `--expires`, `--endpoint`, with `--no-purpose`, `--no-expires`
+  and `--no-endpoint` to clear the nullable ones. `id`, `last4` and the
+  registration date stay uneditable — they describe the value in the keychain,
+  and editing them here would only make the registry lie about it. Rotation
+  stays `pb key add --overwrite`, where a secret is actually being handled and
+  the command should look like it.
+
+- **`pb key list` filters.** `--env NAME` answers "who holds the name my code
+  reads", `--provider P` narrows to one issuer, and `--grep TEXT` matches id,
+  label, purpose, provider and env name. The table gained an ENV column. A
+  listing you have to read in full is a listing an agent reads in full.
+
+- **MCP: `resolve_env_vars`, `update_key`, `list_keys` filters, and `env` on
+  `store_key`.** `resolve_env_vars` is the tool the two rules above hang off:
+  give it the variable names the code reads and it answers per name with `keys`
+  (exact `env` matches), `suggestions` when there are none (entries whose
+  purpose, label or id mention the name or its non-generic tokens), `projects`
+  (env-vault environments defining it), a `status` of `key` / `project_var` /
+  `both` / `suggested` / `missing`, and `use` — the exact `pb key run …` or
+  `pb env run …` that supplies it. It reads two local JSON files and returns no
+  value, which is why it is ungated, and it is the reason the answer to "I need
+  this credential" can be a command rather than a secret. `update_key` is
+  `pb key edit`'s twin over MCP — metadata only, with a `clear` list for
+  `purpose`, `expires_at`, `endpoint` and `env` — ungated for the same reason:
+  it cannot reach the keychain. Rotation stays `store_key` with `overwrite`.
+  `list_keys` takes `provider`, `env` and `query`.
+
+- **Two rules in the MCP server's instructions.** "LOOK HERE BEFORE ASKING FOR
+  A CREDENTIAL": before asking the human, writing a placeholder or calling a
+  variable missing, call `resolve_env_vars`; the answer is how to use the key
+  via `pb key run`, never the value itself. And "NAME THE VARIABLE": register
+  with `env` set, following the convention above, and backfill what lacks one
+  with `update_key`. Instructions are the only part of an MCP server a model
+  reads before deciding what to do, and every gate in this vault was already
+  strong enough — what was missing was the sentence telling it to try.
+
+### Changed
+
+- **The manifest's `KeyRecord` carries `env`.** `pb manifest` exists so a new
+  machine's agent can plan against what the old one used, and "which variable
+  is this key" is exactly the kind of thing that plan needs. It is a name, not
+  a value, so it changes nothing about what the file is safe to commit.
+
 ## [0.6.0] - 2026-08-28
 
 ### Added
diff --git a/README.md b/README.md
index c4f345a..bedfe3b 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@
 - **Switch** — change profile/context from the panel, the CLI, or an AI — including the traps (`gcloud` ADC).
 - **Permissions** — see what your tokens can actually do (`gh` scopes today) and fix missing scopes with one hint.
 - **[MCP client management](docs/mcp-clients.md)** — every MCP server registered in Claude Code, Claude Desktop, Cursor, Codex, Windsurf and VS Code in one matrix; copy a server between clients without hand-editing four files in two formats.
-- **[Key vault](docs/key-vault.md)** — standalone API keys no CLI tracks: values in the macOS Keychain, metadata on disk, provider-aware `pb key verify`, and AI registration over MCP.
+- **[Key vault](docs/key-vault.md)** — standalone API keys no CLI tracks: values in the macOS Keychain, metadata on disk, provider-aware `pb key verify`, AI registration over MCP, and each key filed under the env-var name your code already reads (`CLOUDFLARE_API_TOKEN`) so `pb key run` — or an agent that needs it — can find and inject it without anyone reading the value.
 - **[Project env vault](docs/env-vault.md)** — a project's environment variables without a plaintext `.env`: pull from Infisical, keep hand-set local overrides that never sync back, run a command with the merged result. A project is a portable name, not a path — `pb export` carries the manifest to a new machine (or copy the one file), clone the repo, pull.
 - **[Keeping CLIs current](#keeping-clis-current)** — which tools are outdated, which were renamed out from under you, and the exact command to update each one.
 - **[Migrate](docs/migration.md)** — export to a new machine; whatever can't travel, your AI walks you through re-authing. Or `pb manifest`: the secret-free record of what you use, safe to commit, and enough for an agent to rebuild a machine from.
@@ -52,6 +52,7 @@ pb status            # the whole board in your terminal
 pb use gcloud work   # switch a profile
 pb verify gh         # actually check a token against its API
 pb key list          # your registered API keys
+pb key run cf-deploy -- wrangler deploy  # one credential into one process, never on screen
 pb env run -- bun dev  # this directory's env vars, from the Keychain, no .env file
 ```
 
@@ -141,7 +142,7 @@ table →](docs/migration.md)**
 { "mcpServers": { "patchbay": { "command": "/usr/local/bin/patchbay-mcp" } } }
 ```
 
-Your agent gets `list_connections`, `switch_profile`, `verify`, `get_permissions`, `store_key`, `plan_setup`, and friends — "switch to the work gcloud account and deploy" becomes one sentence, and a key your AI creates mid-task gets registered instead of rotting in a chat log. Where permissions are granted per resource rather than per credential, `get_permissions` takes a `scope` and `list_permission_scopes` says what the choices are — a Google account has no roles of its own, only roles on a project, so patchbay reads the IAM policy of the one you name. Reading secret values back is **off by default** (`PATCHBAY_ALLOW_SECRET_READ=1` to opt in).
+Your agent gets `list_connections`, `switch_profile`, `verify`, `get_permissions`, `store_key`, `plan_setup`, and friends — "switch to the work gcloud account and deploy" becomes one sentence, and a key your AI creates mid-task gets registered instead of rotting in a chat log. It also gets `resolve_env_vars`: hand it the variable names your code reads and it says which vault key or env-vault project holds each one, and the exact `pb key run` / `pb env run` that supplies it — so an agent that needs `CLOUDFLARE_API_TOKEN` looks in your vault instead of asking you for it or writing a placeholder, and still never sees the value. Where permissions are granted per resource rather than per credential, `get_permissions` takes a `scope` and `list_permission_scopes` says what the choices are — a Google account has no roles of its own, only roles on a project, so patchbay reads the IAM policy of the one you name. Reading secret values back is **off by default** (`PATCHBAY_ALLOW_SECRET_READ=1` to opt in).
 
 ## Showcase
 
diff --git a/app/src-tauri/src/lib.rs b/app/src-tauri/src/lib.rs
index ec585b1..1df93ed 100644
--- a/app/src-tauri/src/lib.rs
+++ b/app/src-tauri/src/lib.rs
@@ -187,6 +187,7 @@ async fn key_add(
     scopes: Vec<String>,
     expires: Option<String>,
     endpoint: Option<String>,
+    env: Option<String>,
     secret: String,
     overwrite: bool,
 ) -> CmdResult<KeyRow> {
@@ -212,7 +213,11 @@ async fn key_add(
                 .collect(),
         )
         .expires_at(expires_at)
-        .endpoint(some_text(endpoint));
+        .endpoint(some_text(endpoint))
+        // The variable name code reads this key as. Validated by the registry,
+        // not here, so the panel shows the same corrected-name suggestion the
+        // CLI does instead of a second opinion written in TypeScript.
+        .env(some_text(env));
 
         let registry = KeyRegistry::detect()?;
         let entry = registry.add(new, &secret, overwrite)?;
diff --git a/app/src/components/KeysView.tsx b/app/src/components/KeysView.tsx
index 5332741..bebb65d 100644
--- a/app/src/components/KeysView.tsx
+++ b/app/src/components/KeysView.tsx
@@ -128,6 +128,7 @@ export function KeysView() {
               <tr>
                 <th>id</th>
                 <th>provider</th>
+                <th>env</th>
                 <th>label</th>
                 <th>last 4</th>
                 <th>expiry</th>
@@ -141,6 +142,9 @@ export function KeysView() {
                   <tr>
                     <td className="cell-id">{k.id}</td>
                     <td className="cell-mono">{k.provider}</td>
+                    {/* The second name: what code reads this key as, and what
+                        `pb key run` injects it under. A name, never a value. */}
+                    <td className="cell-mono">{k.env ?? <span className="muted">—</span>}</td>
                     <td>{k.label}</td>
                     {/* The only thing on this page derived from a secret value. */}
                     <td className="cell-mono cell-last4">··{k.last4}</td>
@@ -168,7 +172,7 @@ export function KeysView() {
                   </tr>
                   {confirming === k.id && (
                     <tr className="confirm-row">
-                      <td colSpan={7}>
+                      <td colSpan={8}>
                         <div className="confirm">
                           <span className="confirm-why">
                             Remove <b>{k.id}</b>? This removes the entry and its keychain value; the
@@ -228,6 +232,7 @@ function AddKeyForm({
   onAdded: (row: KeyRow) => void | Promise<void>;
 }>) {
   const [id, setId] = useState("");
+  const [env, setEnv] = useState("");
   const [provider, setProvider] = useState("");
   const [label, setLabel] = useState("");
   const [secret, setSecret] = useState("");
@@ -270,6 +275,7 @@ function AddKeyForm({
             .filter(Boolean),
           expires: expires.trim() || null,
           endpoint: endpoint.trim() || null,
+          env: env.trim() || null,
           overwrite,
         },
         value,
@@ -322,6 +328,25 @@ function AddKeyForm({
             </span>
           </label>
 
+          {/* Not behind the fold: this is the entry's second name, and the one
+              anything other than a human looks it up by. */}
+          <label className="field">
+            <span className="field-key">env</span>
+            <input
+              className="field-input"
+              value={env}
+              onChange={(e) => setEnv(e.target.value)}
+              placeholder="CLOUDFLARE_API_TOKEN"
+              spellCheck={false}
+              autoCapitalize="characters"
+              autoCorrect="off"
+            />
+            <span className="muted small">
+              the variable code reads it as — UPPER_SNAKE_CASE; what{" "}
+              <code>pb key run</code> injects and what an agent looks it up by
+            </span>
+          </label>
+
           <label className="field">
             <span className="field-key">provider</span>
             <input
diff --git a/app/src/types.ts b/app/src/types.ts
index ae40396..f947abc 100644
--- a/app/src/types.ts
+++ b/app/src/types.ts
@@ -297,6 +297,16 @@ export interface KeyRow {
   last4: string;
   /** Who registered it: `"cli"`, `"mcp:<client>"`, `"gui"`. */
   source: string;
+  /**
+   * The environment variable this key is exposed as — `CLOUDFLARE_API_TOKEN`.
+   * A name, never a value: it is the second name for the entry, the one code
+   * and CI already spell, and the one `pb key run` injects the secret under.
+   * `null` for entries that are not variables (an issuer id, a D-U-N-S number)
+   * and for anything registered before the field existed. Core omits the field
+   * entirely when it is unset rather than writing `null`, so read it with `??`
+   * — every consumer here treats absent and null the same way.
+   */
+  env: string | null;
   expiry_state: KeyExpiryState;
 }
 
@@ -317,6 +327,9 @@ export interface NewKeyInput {
   scopes: string[];
   expires: string | null;
   endpoint: string | null;
+  /** UPPER_SNAKE_CASE, or null. Core validates and its refusal spells the
+   *  corrected name, so the panel does not pre-empt it. */
+  env: string | null;
   /** Replace an existing entry under this id — a rotation, not an accident. */
   overwrite: boolean;
 }
diff --git a/crates/patchbay-cli/src/keys.rs b/crates/patchbay-cli/src/keys.rs
index 5cfe96b..085fccb 100644
--- a/crates/patchbay-cli/src/keys.rs
+++ b/crates/patchbay-cli/src/keys.rs
@@ -2,9 +2,10 @@
 //!
 //! Deliberate asymmetry, and the whole point of the design: **writing** a
 //! secret is easy (pipe it in, or type it blind), **reading** one back is not.
-//! There is no `pb key show`. The only way out is [`Command::Copy`], which
-//! moves the value from the keychain to the clipboard without it ever passing
-//! through this process's stdout, a shell history line or a log.
+//! There is no `pb key show`. A value leaves the vault two ways, neither of
+//! them through this process's stdout, a shell history line or a log:
+//! [`Command::Copy`] moves it from the keychain to the clipboard, and
+//! [`Command::Run`] puts it straight into a child process's environment.
 //!
 //! Secrets never arrive as arguments either: argv is world-readable through
 //! `ps` and gets written to `~/.zsh_history` verbatim.
@@ -15,7 +16,10 @@ use std::process::{Command as Process, Stdio};
 use anyhow::{Context, Result};
 use chrono::{DateTime, NaiveDate, NaiveTime, TimeZone, Utc};
 use clap::Subcommand;
-use patchbay_core::keys::{expiring_within_at, KeyEntry, KeyPatch, KeyRegistry, NewKey};
+use patchbay_core::keys::{
+    expiring_within_at, filter_keys, validate_env_name, KeyEntry, KeyFilter, KeyPatch, KeyRegistry,
+    NewKey,
+};
 use patchbay_core::keys_verify::{verify_key, KeyVerifyOutcome, KeyVerifyStatus};
 
 use crate::render::{self, Styles};
@@ -27,7 +31,12 @@ const COL_LAST4: usize = 5;
 const COL_EXPIRES: usize = 16;
 const COL_ID_MAX: usize = 24;
 const COL_PROVIDER_MAX: usize = 12;
-const COL_LABEL_MAX: usize = 24;
+/// The ENV column pays for itself out of LABEL's budget: a variable name is
+/// what a consumer looks a key up by, a label is only ever decoration.
+const COL_ENV_MAX: usize = 22;
+const COL_LABEL_MAX: usize = 18;
+/// Width of the field-name column in `pb key edit`'s report of what changed.
+const FIELD_COL: usize = 9;
 const DASH: &str = "—";
 
 #[derive(Subcommand, Debug)]
@@ -58,6 +67,11 @@ pub enum Command {
         /// `https://<you>.grafana.net`. Grafana needs it to verify.
         #[arg(long, value_name = "URL")]
         endpoint: Option<String>,
+        /// Environment variable the key is exposed as, UPPER_SNAKE_CASE:
+        /// `CLOUDFLARE_API_TOKEN`. What `pb key run` injects it as, and what an
+        /// agent looks it up by.
+        #[arg(long, value_name = "NAME")]
+        env: Option<String>,
         /// Replace an existing entry with the same id (a rotation).
         #[arg(long)]
         overwrite: bool,
@@ -69,9 +83,79 @@ pub enum Command {
         /// Only keys expiring within this many days (already-expired included).
         #[arg(long, value_name = "DAYS")]
         expiring: Option<i64>,
+        /// Only keys from this issuer.
+        #[arg(long, value_name = "P")]
+        provider: Option<String>,
+        /// Only the key(s) exposed as this variable name.
+        #[arg(long, value_name = "NAME")]
+        env: Option<String>,
+        /// Free text over id, label, provider, purpose and variable name.
+        #[arg(long, value_name = "TEXT")]
+        grep: Option<String>,
+    },
+    /// Change a key's metadata. The stored value is never touched.
+    ///
+    /// Every `--no-*` clears its field. `id`, `last4` and the registration date
+    /// are not editable: they describe the value in the keychain, and editing
+    /// them here would only make the registry lie about it.
+    Edit {
+        /// The key to edit.
+        id: String,
+        /// Who issued it: `cloudflare`, `github`, `openai`, … Free-form.
+        #[arg(long)]
+        provider: Option<String>,
+        /// Display name.
+        #[arg(long)]
+        label: Option<String>,
+        /// What it is for, e.g. "deploy from GitHub Actions in repo X".
+        #[arg(long, conflicts_with = "no_purpose")]
+        purpose: Option<String>,
+        /// Forget what this key is for.
+        #[arg(long = "no-purpose")]
+        no_purpose: bool,
+        /// Replace the recorded scopes, comma-separated.
+        #[arg(long, value_delimiter = ',')]
+        scopes: Vec<String>,
+        /// Expiry: `2027-01-01`, or a full RFC 3339 timestamp.
+        #[arg(long, value_name = "DATE", conflicts_with = "no_expires")]
+        expires: Option<String>,
+        /// Forget the expiry.
+        #[arg(long = "no-expires")]
+        no_expires: bool,
+        /// Instance URL, for providers with more than one address.
+        #[arg(long, value_name = "URL", conflicts_with = "no_endpoint")]
+        endpoint: Option<String>,
+        /// Forget the instance URL.
+        #[arg(long = "no-endpoint")]
+        no_endpoint: bool,
+        /// Environment variable the key is exposed as, UPPER_SNAKE_CASE.
+        #[arg(long, value_name = "NAME", conflicts_with = "no_env")]
+        env: Option<String>,
+        /// Forget the variable name.
+        #[arg(long = "no-env")]
+        no_env: bool,
     },
     /// Put a key's value on the clipboard, without printing it.
     Copy { id: String },
+    /// Run a command with keys in its environment.
+    ///
+    /// The blessed path for an agent or a script that needs a credential: the
+    /// value goes keychain → child process and never through a terminal, a log
+    /// or a model's context. The parent environment is inherited and these are
+    /// added to it, so the command still sees the shell it was launched from.
+    #[command(after_help = "Examples:\n  \
+        pb key run cloudflare-api-token-yjack-macbook -- wrangler deploy\n  \
+        pb key run --as CF_TOKEN=cf-deploy neon-peregrine-ci -- ./deploy.sh")]
+    Run {
+        /// Keys to inject, each under its own recorded variable name.
+        keys: Vec<String>,
+        /// Inject ID under NAME for this run, whatever name it is stored with.
+        #[arg(long = "as", value_name = "NAME=ID")]
+        aliases: Vec<String>,
+        /// The command, after `--`.
+        #[arg(last = true, required = true, value_name = "CMD")]
+        command: Vec<String>,
+    },
     /// Ask the issuer whether a key still works.
     ///
     /// Exit codes: 0 verified (or nothing patchbay can check), 1 the provider
@@ -107,6 +191,7 @@ pub fn run(command: Command, styles: &Styles) -> Result<i32> {
             scopes,
             expires,
             endpoint,
+            env,
             overwrite,
         } => {
             let expires_at = expires.as_deref().map(parse_expiry).transpose()?;
@@ -116,7 +201,8 @@ pub fn run(command: Command, styles: &Styles) -> Result<i32> {
                 .purpose(purpose)
                 .scopes(scopes)
                 .expires_at(expires_at)
-                .endpoint(endpoint);
+                .endpoint(endpoint)
+                .env(env);
 
             let secret = read_secret(&id)?;
             let entry = registry.add(new, &secret, overwrite)?;
@@ -126,6 +212,9 @@ pub fn run(command: Command, styles: &Styles) -> Result<i32> {
             if let Some(endpoint) = &entry.endpoint {
                 println!("  instance: {endpoint}");
             }
+            if let Some(name) = &entry.env {
+                println!("  env:      {name}");
+            }
             println!("  value:    {}", registry.store_name());
             println!("  metadata: {}", registry.path().display());
             if provider.is_none() {
@@ -134,26 +223,54 @@ pub fn run(command: Command, styles: &Styles) -> Result<i32> {
             if entry.expires_at.is_none() {
                 println!("  hint: --expires lets patchbay warn you before it dies");
             }
+            if entry.env.is_none() {
+                println!(
+                    "  hint: --env NAME lets `pb key run` and agents find it by the name code reads"
+                );
+            }
             Ok(0)
         }
 
-        Command::List { json, expiring } => {
+        Command::List {
+            json,
+            expiring,
+            provider,
+            env,
+            grep,
+        } => {
+            let filter = KeyFilter {
+                provider,
+                env,
+                query: grep,
+            };
             let mut entries = registry.list()?;
             if let Some(days) = expiring {
                 entries = expiring_within_at(&entries, Utc::now(), days);
             }
+            // After the expiring cut, so the two narrow the same listing rather
+            // than fighting over it.
+            entries = filter_keys(&entries, &filter);
+
             if json {
                 // Machine-readable: JSON only, no ANSI, no extras.
                 println!("{}", serde_json::to_string_pretty(&entries)?);
                 return Ok(0);
             }
             if entries.is_empty() {
-                match expiring {
-                    Some(days) => println!("no registered key expires within {days}d"),
-                    None => {
-                        println!("no keys registered yet");
-                        println!("  pb key add <id> --provider <who> --label \"<what>\"");
-                    }
+                let active = active_filters(expiring, &filter);
+                if active.is_empty() {
+                    println!("no keys registered yet");
+                    println!("  pb key add <id> --provider <who> --label \"<what>\"");
+                } else if filter.is_empty() {
+                    // The expiring-only question deserves its own sentence: an
+                    // empty answer there is good news, not a failed search.
+                    println!(
+                        "no registered key expires within {}d",
+                        expiring.unwrap_or_default()
+                    );
+                } else {
+                    println!("no registered key matches");
+                    println!("  filters: {}", active.join(", "));
                 }
                 return Ok(0);
             }
@@ -161,6 +278,69 @@ pub fn run(command: Command, styles: &Styles) -> Result<i32> {
             Ok(0)
         }
 
+        Command::Edit {
+            id,
+            provider,
+            label,
+            purpose,
+            no_purpose,
+            scopes,
+            expires,
+            no_expires,
+            endpoint,
+            no_endpoint,
+            env,
+            no_env,
+        } => {
+            let mut patch = KeyPatch::default();
+            let mut touched: Vec<Field> = Vec::new();
+
+            if let Some(provider) = provider {
+                patch.provider = Some(provider);
+                touched.push(Field::Provider);
+            }
+            if let Some(label) = label {
+                patch.label = Some(label);
+                touched.push(Field::Label);
+            }
+            if no_purpose || purpose.is_some() {
+                patch.purpose = Some(purpose);
+                touched.push(Field::Purpose);
+            }
+            if !scopes.is_empty() {
+                patch.scopes = Some(scopes);
+                touched.push(Field::Scopes);
+            }
+            if no_expires || expires.is_some() {
+                patch.expires_at = Some(expires.as_deref().map(parse_expiry).transpose()?);
+                touched.push(Field::Expires);
+            }
+            if no_endpoint || endpoint.is_some() {
+                patch.endpoint = Some(endpoint);
+                touched.push(Field::Endpoint);
+            }
+            if no_env || env.is_some() {
+                patch.env = Some(env);
+                touched.push(Field::Env);
+            }
+            if patch.is_empty() {
+                anyhow::bail!(
+                    "nothing to change; pass at least one of --provider, --label, --purpose, \
+                     --scopes, --expires, --endpoint, --env (or a --no-* to clear one)"
+                );
+            }
+
+            // A rejected name (`pb key edit x --env cf_token`) surfaces the
+            // core's error verbatim: it already suggests the right spelling.
+            let updated = registry.update_metadata(&id, patch)?;
+            println!("updated {}", updated.id);
+            for field in touched {
+                let name = format!("{}:", field.label());
+                println!("  {name:<FIELD_COL$} {}", field.value(&updated));
+            }
+            Ok(0)
+        }
+
         Command::Copy { id } => {
             let entry = registry
                 .get(&id)?
@@ -173,6 +353,62 @@ pub fn run(command: Command, styles: &Styles) -> Result<i32> {
             Ok(0)
         }
 
+        Command::Run {
+            keys,
+            aliases,
+            command,
+        } => {
+            let (bin, args) = command
+                .split_first()
+                .ok_or_else(|| anyhow::anyhow!("nothing to run; pass a command after `--`"))?;
+            let aliases = parse_aliases(&aliases)?;
+
+            // Everything is resolved before anything is spawned: a typo has to
+            // fail here, not halfway through a deploy.
+            let mut entries: Vec<KeyEntry> = Vec::new();
+            for id in keys.iter().chain(aliases.iter().map(|(_, id)| id)) {
+                if entries.iter().any(|e| &e.id == id) {
+                    continue;
+                }
+                entries.push(
+                    registry
+                        .get(id)?
+                        .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?,
+                );
+            }
+            let plan = injection_plan(&entries, &keys, &aliases)?;
+
+            // stderr, so a command whose stdout is being piped stays clean —
+            // and names only, never a value or a fragment of one.
+            let named: Vec<String> = plan
+                .iter()
+                .map(|(name, id)| format!("{name} ({id})"))
+                .collect();
+            eprintln!("injecting {} into `{bin}`", named.join(", "));
+
+            let mut child = std::process::Command::new(bin);
+            child.args(args);
+            // The parent environment is inherited on purpose: unlike
+            // `pb env run`, this adds a few credentials to an otherwise normal
+            // shell rather than defining the whole environment.
+            for (name, id) in &plan {
+                let secret = registry.get_secret(id)?;
+                child.env(name, &secret);
+                drop(secret);
+            }
+            let status = child
+                .status()
+                .with_context(|| format!("could not run `{bin}`"))?;
+
+            match status.code() {
+                Some(code) => Ok(code),
+                None => {
+                    eprintln!("pb: `{bin}` was killed by a signal");
+                    Ok(1)
+                }
+            }
+        }
+
         Command::Verify {
             id,
             json,
@@ -306,6 +542,155 @@ fn print_verify(entry: &KeyEntry, outcome: &KeyVerifyOutcome, updated: &[String]
     }
 }
 
+// ---------------------------------------------------------------------------
+// edit
+// ---------------------------------------------------------------------------
+
+/// An editable metadata field, so `pb key edit` can report what it changed by
+/// reading the *stored* entry back rather than echoing what was typed —
+/// trimming and normalization happen in the core, and the report should show
+/// what actually landed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum Field {
+    Provider,
+    Label,
+    Purpose,
+    Scopes,
+    Expires,
+    Endpoint,
+    Env,
+}
+
+impl Field {
+    fn label(self) -> &'static str {
+        match self {
+            Self::Provider => "provider",
+            Self::Label => "label",
+            Self::Purpose => "purpose",
+            Self::Scopes => "scopes",
+            Self::Expires => "expires",
+            Self::Endpoint => "endpoint",
+            Self::Env => "env",
+        }
+    }
+
+    /// This field on `entry`, as one line. A cleared field reads as a dash.
+    fn value(self, entry: &KeyEntry) -> String {
+        let or_dash = |v: Option<String>| v.unwrap_or_else(|| DASH.to_string());
+        match self {
+            Self::Provider => entry.provider.clone(),
+            Self::Label => entry.label.clone(),
+            Self::Purpose => or_dash(entry.purpose.as_deref().map(one_line)),
+            Self::Scopes => {
+                if entry.scopes.is_empty() {
+                    DASH.to_string()
+                } else {
+                    entry.scopes.join(", ")
+                }
+            }
+            Self::Expires => or_dash(entry.expires_at.map(|at| at.format("%Y-%m-%d").to_string())),
+            Self::Endpoint => or_dash(entry.endpoint.clone()),
+            Self::Env => or_dash(entry.env.clone()),
+        }
+    }
+}
+
+/// The filters a listing was narrowed by, for the "nothing matched" line. An
+/// empty answer is only useful next to the question that produced it.
+fn active_filters(expiring: Option<i64>, filter: &KeyFilter) -> Vec<String> {
+    let mut active = Vec::new();
+    if let Some(p) = &filter.provider {
+        active.push(format!("provider={p}"));
+    }
+    if let Some(e) = &filter.env {
+        active.push(format!("env={e}"));
+    }
+    if let Some(q) = &filter.query {
+        active.push(format!("grep={q}"));
+    }
+    if let Some(days) = expiring {
+        active.push(format!("expiring={days}d"));
+    }
+    active
+}
+
+// ---------------------------------------------------------------------------
+// run
+// ---------------------------------------------------------------------------
+
+/// `NAME=ID`, split on the first `=` so a key id containing one is still
+/// readable. The name is held to the same shape a stored one is: an alias is a
+/// variable name too, and a run is no excuse to invent a second spelling.
+fn parse_aliases(raw: &[String]) -> Result<Vec<(String, String)>> {
+    raw.iter()
+        .map(|spec| {
+            let (name, id) = spec.split_once('=').ok_or_else(|| {
+                anyhow::anyhow!(
+                    "`{spec}` is not a NAME=ID pair; write it like \
+                     --as CF_TOKEN=cloudflare-api-token"
+                )
+            })?;
+            let (name, id) = (name.trim(), id.trim());
+            validate_env_name(name)?;
+            if id.is_empty() {
+                anyhow::bail!(
+                    "`--as {spec}` names no key; write it like \
+                     --as CF_TOKEN=cloudflare-api-token"
+                );
+            }
+            Ok((name.to_string(), id.to_string()))
+        })
+        .collect()
+}
+
+/// The `(variable name, key id)` pairs a run injects, in the order they were
+/// asked for: positional ids under their recorded name, then the `--as`
+/// aliases. Pure, so the whole resolution can be tested without a keychain.
+///
+/// Two ids landing on one name is refused rather than resolved: silently
+/// letting the later one win would hand a command a credential the caller did
+/// not think they were passing.
+fn injection_plan(
+    entries: &[KeyEntry],
+    ids: &[String],
+    aliases: &[(String, String)],
+) -> Result<Vec<(String, String)>> {
+    let mut plan: Vec<(String, String)> = Vec::new();
+    let mut add = |name: String, id: String| -> Result<()> {
+        // The same injection asked for twice (positionally and by alias) is
+        // one injection, not a collision.
+        if plan.iter().any(|(n, i)| n == &name && i == &id) {
+            return Ok(());
+        }
+        if let Some((_, other)) = plan.iter().find(|(n, _)| n == &name) {
+            anyhow::bail!(
+                "`{other}` and `{id}` would both be injected as {name}; \
+                 give one of them another name with `--as OTHER_NAME={id}`"
+            );
+        }
+        plan.push((name, id));
+        Ok(())
+    };
+
+    for id in ids {
+        let entry = entries
+            .iter()
+            .find(|e| &e.id == id)
+            .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
+        let name = entry.env.clone().ok_or_else(|| {
+            anyhow::anyhow!(
+                "`{id}` has no env name; set one with `pb key edit {id} --env NAME`, \
+                 or pass --as NAME={id} for this run"
+            )
+        })?;
+        add(name, id.clone())?;
+    }
+    for (name, id) in aliases {
+        add(name.clone(), id.clone())?;
+    }
+    Ok(plan)
+}
+
 // ---------------------------------------------------------------------------
 // input
 // ---------------------------------------------------------------------------
@@ -427,21 +812,29 @@ pub fn render_table(entries: &[KeyEntry], now: DateTime<Utc>, styles: &Styles) -
         "PROVIDER",
         COL_PROVIDER_MAX,
     );
+    let env_w = column_width(
+        entries
+            .iter()
+            .map(|e| e.env.as_deref().map_or(0, |v| v.chars().count())),
+        "ENV",
+        COL_ENV_MAX,
+    );
     let label_w = column_width(
         entries.iter().map(|e| e.label.chars().count()),
         "LABEL",
         COL_LABEL_MAX,
     );
-    let fixed = id_w + provider_w + label_w + COL_LAST4 + COL_EXPIRES + GAP * 5;
+    let fixed = id_w + provider_w + env_w + label_w + COL_LAST4 + COL_EXPIRES + GAP * 6;
     let purpose_w = TABLE_WIDTH.saturating_sub(fixed).max(12);
 
     let gap = " ".repeat(GAP);
     let mut out = String::new();
 
     let header = format!(
-        "{}{gap}{}{gap}{}{gap}{}{gap}{}{gap}{}",
+        "{}{gap}{}{gap}{}{gap}{}{gap}{}{gap}{}{gap}{}",
         pad("ID", id_w),
         pad("PROVIDER", provider_w),
+        pad("ENV", env_w),
         pad("LABEL", label_w),
         pad("LAST4", COL_LAST4),
         pad("EXPIRES", COL_EXPIRES),
@@ -453,6 +846,12 @@ pub fn render_table(entries: &[KeyEntry], now: DateTime<Utc>, styles: &Styles) -
     for entry in entries {
         let id = pad(&render::truncate(&entry.id, id_w), id_w);
         let provider = pad(&render::truncate(&entry.provider, provider_w), provider_w);
+        // No variable name is a fact about the key, not a warning — same
+        // treatment as a missing expiry.
+        let env = match &entry.env {
+            Some(name) => pad(&render::truncate(name, env_w), env_w),
+            None => styles.paint(dim(), &pad(DASH, env_w)),
+        };
         let label = pad(&render::truncate(&entry.label, label_w), label_w);
         let last4 = pad(&entry.last4, COL_LAST4);
 
@@ -476,8 +875,9 @@ pub fn render_table(entries: &[KeyEntry], now: DateTime<Utc>, styles: &Styles) -
             styles.paint(dim(), &purpose)
         };
 
-        let line =
-            format!("{id}{gap}{provider}{gap}{label}{gap}{last4}{gap}{expires}{gap}{purpose}");
+        let line = format!(
+            "{id}{gap}{provider}{gap}{env}{gap}{label}{gap}{last4}{gap}{expires}{gap}{purpose}"
+        );
         out.push_str(line.trim_end());
         out.push('\n');
     }
@@ -527,6 +927,13 @@ mod tests {
         }
     }
 
+    fn with_env(id: &str, env: Option<&str>) -> KeyEntry {
+        KeyEntry {
+            env: env.map(Into::into),
+            ..entry(id, None)
+        }
+    }
+
     #[test]
     fn test_table_is_plain_and_aligned_without_color() {
         let entries = vec![
@@ -552,6 +959,43 @@ mod tests {
         assert!(lines[2][col..].starts_with("cloudflare"));
     }
 
+    #[test]
+    fn test_env_column_sits_between_provider_and_label() {
+        let entries = vec![
+            with_env("cf-deploy", Some("CLOUDFLARE_API_TOKEN")),
+            with_env("duns", None),
+        ];
+        let out = render_table(&entries, now(), &Styles::new(false));
+        let lines: Vec<&str> = out.lines().collect();
+
+        let provider_col = lines[0].find("PROVIDER").unwrap();
+        let env_col = lines[0].find("ENV").unwrap();
+        let label_col = lines[0].find("LABEL").unwrap();
+        assert!(provider_col < env_col && env_col < label_col, "{out}");
+
+        assert!(
+            lines[1][env_col..].starts_with("CLOUDFLARE_API_TOKEN"),
+            "{out}"
+        );
+        // No name is a dash in the same column, not a hole in the row.
+        assert!(lines[2][env_col..].starts_with(DASH), "{out}");
+        assert!(
+            lines[1][label_col..].starts_with("CF deploy token"),
+            "{out}"
+        );
+    }
+
+    #[test]
+    fn test_a_long_env_name_is_truncated_into_its_column() {
+        let long = "A".repeat(COL_ENV_MAX + 20);
+        let out = render_table(&[with_env("k", Some(&long))], now(), &Styles::new(false));
+        assert!(!out.contains(&long), "{out}");
+        assert!(
+            out.contains(&format!("{}…", "A".repeat(COL_ENV_MAX - 1))),
+            "{out}"
+        );
+    }
+
     #[test]
     fn test_table_never_shows_a_secret_field() {
         // The only thing derived from the value that may appear is last4.
@@ -680,6 +1124,179 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_parse_aliases_splits_on_the_first_equals_and_validates_the_name() {
+        let raw = |v: &[&str]| -> Vec<String> { v.iter().map(|s| s.to_string()).collect() };
+
+        assert_eq!(
+            parse_aliases(&raw(&["CF_TOKEN=cf-deploy", " NEON_API_KEY = neon-ci "])).unwrap(),
+            vec![
+                ("CF_TOKEN".to_string(), "cf-deploy".to_string()),
+                ("NEON_API_KEY".to_string(), "neon-ci".to_string()),
+            ]
+        );
+        // An id may contain `=`; only the first one separates.
+        assert_eq!(
+            parse_aliases(&raw(&["TOKEN=weird=id"])).unwrap(),
+            vec![("TOKEN".to_string(), "weird=id".to_string())]
+        );
+
+        let err = parse_aliases(&raw(&["CF_TOKEN"])).unwrap_err().to_string();
+        assert!(err.contains("NAME=ID"), "{err}");
+        let err = parse_aliases(&raw(&["CF_TOKEN="])).unwrap_err().to_string();
+        assert!(err.contains("names no key"), "{err}");
+        // The core owns the shape rule, and its suggestion comes through.
+        let err = parse_aliases(&raw(&["cf_token=cf-deploy"]))
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("UPPER_SNAKE_CASE"), "{err}");
+        assert!(err.contains("`CF_TOKEN`"), "{err}");
+    }
+
+    #[test]
+    fn test_injection_plan_uses_the_recorded_name_and_lets_an_alias_override_it() {
+        let entries = vec![
+            with_env("cf-deploy", Some("CLOUDFLARE_API_TOKEN")),
+            with_env("neon-ci", Some("NEON_API_KEY")),
+        ];
+        let ids = |v: &[&str]| -> Vec<String> { v.iter().map(|s| s.to_string()).collect() };
+        let alias = |name: &str, id: &str| (name.to_string(), id.to_string());
+
+        assert_eq!(
+            injection_plan(&entries, &ids(&["cf-deploy", "neon-ci"]), &[]).unwrap(),
+            vec![
+                alias("CLOUDFLARE_API_TOKEN", "cf-deploy"),
+                alias("NEON_API_KEY", "neon-ci"),
+            ]
+        );
+
+        // An alias alone: no positional id needed.
+        assert_eq!(
+            injection_plan(&entries, &[], &[alias("CF_TOKEN", "cf-deploy")]).unwrap(),
+            vec![alias("CF_TOKEN", "cf-deploy")]
+        );
+
+        // The same key both ways is two injections under two names.
+        assert_eq!(
+            injection_plan(
+                &entries,
+                &ids(&["cf-deploy"]),
+                &[alias("CF_TOKEN", "cf-deploy")]
+            )
+            .unwrap(),
+            vec![
+                alias("CLOUDFLARE_API_TOKEN", "cf-deploy"),
+                alias("CF_TOKEN", "cf-deploy"),
+            ]
+        );
+
+        // ...and asking for the very same injection twice is not a collision.
+        assert_eq!(
+            injection_plan(
+                &entries,
+                &ids(&["cf-deploy"]),
+                &[alias("CLOUDFLARE_API_TOKEN", "cf-deploy")]
+            )
+            .unwrap(),
+            vec![alias("CLOUDFLARE_API_TOKEN", "cf-deploy")]
+        );
+    }
+
+    #[test]
+    fn test_injection_plan_refuses_a_key_with_no_name_and_a_collision() {
+        let entries = vec![
+            with_env("cf-deploy", Some("CLOUDFLARE_API_TOKEN")),
+            with_env("cf-r2", Some("CLOUDFLARE_API_TOKEN")),
+            with_env("duns", None),
+        ];
+        let ids = |v: &[&str]| -> Vec<String> { v.iter().map(|s| s.to_string()).collect() };
+
+        let err = injection_plan(&entries, &ids(&["duns"]), &[])
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("has no env name"), "{err}");
+        assert!(err.contains("pb key edit duns --env NAME"), "{err}");
+        assert!(err.contains("--as NAME=duns"), "{err}");
+
+        // Two keys of one provider share a conventional name; the run has to
+        // say which is which rather than let the second win.
+        let err = injection_plan(&entries, &ids(&["cf-deploy", "cf-r2"]), &[])
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("cf-deploy"), "{err}");
+        assert!(err.contains("cf-r2"), "{err}");
+        assert!(err.contains("CLOUDFLARE_API_TOKEN"), "{err}");
+
+        let err = injection_plan(&entries, &ids(&["ghost"]), &[])
+            .unwrap_err()
+            .to_string();
+        assert!(err.contains("no key registered as `ghost`"), "{err}");
+    }
+
+    #[test]
+    fn test_edit_reports_a_cleared_field_as_a_dash() {
+        let mut e = entry("k", Some(now()));
+        e.env = Some("CLOUDFLARE_API_TOKEN".into());
+
+        assert_eq!(Field::Provider.value(&e), "cloudflare");
+        assert_eq!(Field::Env.value(&e), "CLOUDFLARE_API_TOKEN");
+        assert_eq!(Field::Scopes.value(&e), "workers:edit");
+        assert_eq!(Field::Expires.value(&e), "2026-01-01");
+        // A multi-line purpose is flattened, exactly as in the table.
+        assert_eq!(Field::Purpose.value(&e), "deploy from GitHub Actions");
+
+        let cleared = KeyEntry {
+            purpose: None,
+            scopes: vec![],
+            expires_at: None,
+            endpoint: None,
+            env: None,
+            ..e
+        };
+        for field in [
+            Field::Purpose,
+            Field::Scopes,
+            Field::Expires,
+            Field::Endpoint,
+            Field::Env,
+        ] {
+            assert_eq!(field.value(&cleared), DASH, "{}", field.label());
+        }
+        // Every label, plus its colon, fits the column the report pads to.
+        for field in [
+            Field::Provider,
+            Field::Label,
+            Field::Purpose,
+            Field::Scopes,
+            Field::Expires,
+            Field::Endpoint,
+            Field::Env,
+        ] {
+            assert!(field.label().len() < FIELD_COL, "{}", field.label());
+        }
+    }
+
+    #[test]
+    fn test_active_filters_names_the_question_an_empty_listing_answered() {
+        assert!(active_filters(None, &KeyFilter::default()).is_empty());
+        assert_eq!(
+            active_filters(
+                Some(30),
+                &KeyFilter {
+                    provider: Some("cloudflare".into()),
+                    env: Some("CLOUDFLARE_API_TOKEN".into()),
+                    query: Some("deploy".into()),
+                }
+            ),
+            vec![
+                "provider=cloudflare",
+                "env=CLOUDFLARE_API_TOKEN",
+                "grep=deploy",
+                "expiring=30d",
+            ]
+        );
+    }
+
     #[test]
     fn test_parse_expiry_accepts_a_bare_date_and_rfc3339() {
         assert_eq!(
diff --git a/crates/patchbay-core/src/keys.rs b/crates/patchbay-core/src/keys.rs
index 92bb333..4b277e3 100644
--- a/crates/patchbay-core/src/keys.rs
+++ b/crates/patchbay-core/src/keys.rs
@@ -743,7 +743,12 @@ impl KeyFilter {
         if !eq(&self.env, entry.env.as_deref()) {
             return false;
         }
-        match self.query.as_deref().map(str::trim).filter(|q| !q.is_empty()) {
+        match self
+            .query
+            .as_deref()
+            .map(str::trim)
+            .filter(|q| !q.is_empty())
+        {
             None => true,
             Some(q) => {
                 let q = q.to_lowercase();
@@ -1516,7 +1521,9 @@ mod tests {
         assert!(validate_env_name("NEXT_PUBLIC_GA4_ID").is_ok());
         assert!(validate_env_name("A").is_ok());
 
-        let err = validate_env_name("cloudflare-api-token").unwrap_err().to_string();
+        let err = validate_env_name("cloudflare-api-token")
+            .unwrap_err()
+            .to_string();
         assert!(err.contains("UPPER_SNAKE_CASE"), "{err}");
         assert!(err.contains("`CLOUDFLARE_API_TOKEN`"), "{err}");
 
@@ -1634,13 +1641,31 @@ mod tests {
             env: env.map(Into::into),
         };
         let entries = vec![
-            entry("cf-deploy", "cloudflare", Some("CLOUDFLARE_API_TOKEN"), "deploy workers"),
-            entry("cf-r2", "Cloudflare", Some("R2_SECRET_ACCESS_KEY"), "R2 uploads"),
-            entry("neon-ci", "neon", Some("NEON_API_KEY"), "control plane for peregrine"),
+            entry(
+                "cf-deploy",
+                "cloudflare",
+                Some("CLOUDFLARE_API_TOKEN"),
+                "deploy workers",
+            ),
+            entry(
+                "cf-r2",
+                "Cloudflare",
+                Some("R2_SECRET_ACCESS_KEY"),
+                "R2 uploads",
+            ),
+            entry(
+                "neon-ci",
+                "neon",
+                Some("NEON_API_KEY"),
+                "control plane for peregrine",
+            ),
             entry("duns", "dnb", None, "not a secret, an index entry"),
         ];
         let ids = |f: KeyFilter| -> Vec<String> {
-            filter_keys(&entries, &f).into_iter().map(|e| e.id).collect()
+            filter_keys(&entries, &f)
+                .into_iter()
+                .map(|e| e.id)
+                .collect()
         };
 
         assert!(KeyFilter::default().is_empty());
diff --git a/crates/patchbay-core/src/lib.rs b/crates/patchbay-core/src/lib.rs
index de766a5..7660d8c 100644
--- a/crates/patchbay-core/src/lib.rs
+++ b/crates/patchbay-core/src/lib.rs
@@ -57,7 +57,10 @@ pub use envs::{
     Attachment, EnvLayer, EnvMeta, EnvRegistry, EnvVarInfo, EnvVarSource, MergedEnv, ProjectEntry,
     SyncConfig,
 };
-pub use keys::{filter_keys, validate_env_name, KeyEntry, KeyExpiryState, KeyFilter, KeyPatch, KeyRegistry, NewKey};
+pub use keys::{
+    filter_keys, validate_env_name, KeyEntry, KeyExpiryState, KeyFilter, KeyPatch, KeyRegistry,
+    NewKey,
+};
 pub use keys_verify::{verify_key, KeyVerifyOutcome, KeyVerifyStatus};
 pub use keystore::Keystore;
 pub use mcp_clients::{
diff --git a/crates/patchbay-mcp/src/keys.rs b/crates/patchbay-mcp/src/keys.rs
index 4c4e04d..e5ebb08 100644
--- a/crates/patchbay-mcp/src/keys.rs
+++ b/crates/patchbay-mcp/src/keys.rs
@@ -1,20 +1,29 @@
 //! The key vault's MCP surface.
 //!
-//! `store_key` is the headline: an agent that just created a Cloudflare token
-//! or a provider key registers it here, and the machine keeps knowing about it
-//! long after the conversation is gone. Everything else exists to keep that
-//! honest — `list_keys` returns metadata only, and the two dangerous calls
-//! (`get_key`, `remove_key`) are refused unless the *user* started the server
-//! with [`ALLOW_SECRET_READ`] set.
+//! Two headlines, one per direction. `store_key` is the write side: an agent
+//! that just created a Cloudflare token or a provider key registers it here,
+//! and the machine keeps knowing about it long after the conversation is gone.
+//! `resolve_env_vars` is the read side, and the one a task actually reaches
+//! for: it takes the variable names the code reads — `CLOUDFLARE_API_TOKEN`,
+//! `DATABASE_URL` — and answers which of them this machine can already supply,
+//! matching each entry by its `env` name, the UPPER_SNAKE_CASE second name a
+//! key is exposed under. `update_key` keeps those two in step by backfilling an
+//! `env` name onto an entry that never got one.
+//!
+//! Everything else exists to keep that honest — `list_keys` returns metadata
+//! only, and the two dangerous calls (`get_key`, `remove_key`) are refused
+//! unless the *user* started the server with [`ALLOW_SECRET_READ`] set.
 //!
 //! Kept in its own `#[tool_router]` impl block, merged into the main router in
 //! [`crate::server`], so the vault's tools and the connection tools stay
 //! separable.
 
+use std::collections::BTreeSet;
+
 use chrono::{DateTime, Utc};
 use patchbay_core::keys::NewKey;
 use patchbay_core::keys_verify::verify_key;
-use patchbay_core::KeyEntry;
+use patchbay_core::{filter_keys, EnvVarInfo, EnvVarSource, KeyEntry, KeyFilter, KeyPatch};
 use rmcp::handler::server::wrapper::Parameters;
 use rmcp::model::CallToolResult;
 use rmcp::{tool, tool_router, ErrorData, Peer, RoleServer};
@@ -100,6 +109,13 @@ pub struct StoreKeyParams {
     /// address to ask without it. Omit for cloudflare and github, which have
     /// one API each.
     pub endpoint: Option<String>,
+    /// The environment variable this key is exposed as, UPPER_SNAKE_CASE:
+    /// "CLOUDFLARE_API_TOKEN", "NEON_API_KEY". Use the exact name the code, CI
+    /// secret or vendor SDK already reads; otherwise
+    /// <PROVIDER>_<THING>_<KIND>. This is what `pb key run` injects the value
+    /// as and what resolve_env_vars finds the entry by — fill it whenever you
+    /// know it.
+    pub env: Option<String>,
     /// When it expires, RFC 3339 ("2027-01-01T00:00:00Z") or "2027-01-01".
     /// Omit only when the key genuinely never expires — this is what lets
     /// patchbay warn the user before something breaks.
@@ -118,6 +134,79 @@ pub struct KeyIdParams {
     pub id: String,
 }
 
+/// `{ "env": "CLOUDFLARE_API_TOKEN" }` — how a listing is narrowed.
+///
+/// Every field is optional and the struct itself is `#[serde(default)]`, which
+/// is what keeps a bare `list_keys` (no `arguments` at all in the request, so
+/// rmcp hands the extractor an empty object) working exactly as it did before
+/// the filters existed.
+#[derive(Debug, Default, Deserialize, JsonSchema)]
+#[serde(default)]
+pub struct ListKeysParams {
+    /// Who issued the key: "cloudflare", "github". Case-insensitive, and an
+    /// exact match — not a substring; use `query` for a partial name.
+    pub provider: Option<String>,
+    /// The environment variable name an entry is exposed as,
+    /// "CLOUDFLARE_API_TOKEN". Case-insensitive exact match. This is the
+    /// narrowest filter there is: pass it whenever you know the variable the
+    /// task needs.
+    pub env: Option<String>,
+    /// Free text, matched case-insensitively against id, label, provider,
+    /// purpose and env. Use it when you know roughly what the key is for
+    /// ("grafana", "app store") but not its id.
+    pub query: Option<String>,
+}
+
+/// `{ "id": "cf-api", "env": "CLOUDFLARE_API_TOKEN" }` — a metadata patch.
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct UpdateKeyParams {
+    /// The key's id, as listed by `list_keys`. This names the entry to change
+    /// and is never itself changed; a key cannot be renamed.
+    pub id: String,
+    /// New issuer name, when the entry was filed under the wrong one.
+    pub provider: Option<String>,
+    /// New display name.
+    pub label: Option<String>,
+    /// What the key is for, in a sentence the user will understand later.
+    /// Replaces the existing purpose rather than appending to it, so carry
+    /// over anything worth keeping.
+    pub purpose: Option<String>,
+    /// Granted scopes, as the issuer names them. Replaces the whole list.
+    pub scopes: Option<Vec<String>>,
+    /// When it expires, RFC 3339 ("2027-01-01T00:00:00Z") or "2027-01-01".
+    pub expires_at: Option<String>,
+    /// Base URL of the instance this key is for, for providers that are not
+    /// one global service.
+    pub endpoint: Option<String>,
+    /// The environment variable this key is exposed as, UPPER_SNAKE_CASE:
+    /// "CLOUDFLARE_API_TOKEN", "NEON_API_KEY". The field to backfill the
+    /// moment you learn the name for an entry that has none — the purpose
+    /// often says it ("same value as the GitHub secret NEON_API_KEY"). A name
+    /// that is not UPPER_SNAKE_CASE is refused, and the refusal spells the
+    /// corrected one.
+    pub env: Option<String>,
+    /// Fields to blank, by name: any of "purpose", "expires_at", "endpoint",
+    /// "env". Naming a field here AND passing a value for it is an error —
+    /// pass one or the other.
+    pub clear: Option<Vec<String>>,
+}
+
+/// `{ "names": ["CLOUDFLARE_API_TOKEN", "DATABASE_URL"] }` — the variables a
+/// task needs.
+#[derive(Debug, Deserialize, JsonSchema)]
+pub struct ResolveEnvVarsParams {
+    /// The variable names the task reads, spelled exactly as they appear in
+    /// the code, the `.env` or the CI config: ["CLOUDFLARE_API_TOKEN",
+    /// "DATABASE_URL"]. One to 50 of them; matching is case-insensitive. Ask
+    /// for the names you actually need, not the whole file.
+    pub names: Vec<String>,
+    /// Optional: limit the env-vault half of the answer to one project id, as
+    /// `list_env_projects` reports it. Omit it — the default — to search every
+    /// registered project and every one of its environments, which is what you
+    /// want when you do not already know the project.
+    pub project: Option<String>,
+}
+
 /// Metadata plus a derived expiry state, so a caller does not have to do date
 /// arithmetic to notice something is dead.
 fn describe(entry: &KeyEntry, now: DateTime<Utc>) -> Result<serde_json::Value, ErrorData> {
@@ -137,6 +226,284 @@ fn describe(entry: &KeyEntry, now: DateTime<Utc>) -> Result<serde_json::Value, E
     Ok(value)
 }
 
+// ---------------------------------------------------------------------------
+// resolving a wanted variable name against what this machine already holds
+// ---------------------------------------------------------------------------
+
+/// The nullable fields `update_key` can blank. `id`, `created_at` and `last4`
+/// describe the stored value and are immutable; the rest are replaced by
+/// passing a new value.
+const CLEARABLE_FIELDS: [&str; 4] = ["purpose", "expires_at", "endpoint", "env"];
+
+/// Name fragments that identify nothing on their own. `API`, `KEY` and `TOKEN`
+/// are in every second variable on the machine, so matching on them alone
+/// would offer the whole vault as a suggestion for every lookup.
+const GENERIC_TOKENS: [&str; 12] = [
+    "api", "key", "token", "secret", "id", "url", "private", "public", "access", "next", "app",
+    "client",
+];
+
+/// Upper bound on suggestions for one name. This is a guess to confirm, not a
+/// listing: five is already more than a user wants to read.
+const MAX_SUGGESTIONS: usize = 5;
+
+/// Upper bound on names per `resolve_env_vars` call.
+const MAX_RESOLVE_NAMES: usize = 50;
+
+/// The sentence that has to survive every rendering of the answer: what the
+/// caller is holding is a route to the value, not the value.
+const RESOLVE_NOTE: &str = "Values are never returned. Run the command through `pb key run` / \
+`pb env run` so the secret goes keychain -> child process without passing through the \
+conversation. A suggestion is a guess: confirm with the user, then record it with update_key so \
+the next lookup is exact.";
+
+/// Parse and validate the `clear` list. Split out from the tool so the rule —
+/// which fields may be blanked, and what the refusal says — is testable
+/// without a registry.
+fn clear_set(clear: &[String]) -> Result<BTreeSet<String>, String> {
+    let mut out = BTreeSet::new();
+    for field in clear {
+        let field = field.trim().to_ascii_lowercase();
+        if !CLEARABLE_FIELDS.contains(&field.as_str()) {
+            return Err(format!(
+                "cannot clear `{field}`: the fields that can be blanked are {}. Every other field \
+                 is changed by passing a new value, and `id`, `created_at` and `last4` never \
+                 change at all.",
+                CLEARABLE_FIELDS.join(", ")
+            ));
+        }
+        out.insert(field);
+    }
+    Ok(out)
+}
+
+/// An entry that looks like a wanted name without being named it, plus the
+/// reason it was offered — a suggestion the caller cannot explain is one they
+/// cannot confirm with the user.
+#[derive(Debug, Clone, PartialEq)]
+struct Suggestion {
+    entry: KeyEntry,
+    why: String,
+}
+
+/// One environment of one registered project that already carries the name.
+#[derive(Debug, Clone, PartialEq)]
+struct ProjectHit {
+    project: String,
+    env: String,
+    source: EnvVarSource,
+}
+
+/// Everything this machine can say about one wanted variable name.
+#[derive(Debug, Clone, PartialEq)]
+struct ResolvedVar {
+    name: String,
+    keys: Vec<KeyEntry>,
+    suggestions: Vec<Suggestion>,
+    projects: Vec<ProjectHit>,
+}
+
+impl ResolvedVar {
+    /// Whether the machine can supply this name outright. A suggestion is
+    /// explicitly not this: it is a guess waiting on a human.
+    fn is_supplied(&self) -> bool {
+        !self.keys.is_empty() || !self.projects.is_empty()
+    }
+
+    fn status(&self) -> &'static str {
+        match (!self.keys.is_empty(), !self.projects.is_empty()) {
+            (true, true) => "both",
+            (true, false) => "key",
+            (false, true) => "project_var",
+            (false, false) if !self.suggestions.is_empty() => "suggested",
+            (false, false) => "missing",
+        }
+    }
+
+    /// The command that puts the value where the task needs it without anyone
+    /// reading it. A registered key wins over a project variable (it is the
+    /// human's own credential, and the id is unambiguous); a suggestion only
+    /// ever yields the two-step form, because the first step is a decision.
+    fn use_command(&self) -> Option<String> {
+        if let Some(first) = self.keys.first() {
+            let mut command = format!("pb key run {} -- <cmd>", first.id);
+            if self.keys.len() > 1 {
+                let others: Vec<&str> = self.keys[1..].iter().map(|e| e.id.as_str()).collect();
+                command.push_str(&format!("  # or: {}", others.join(", ")));
+            }
+            return Some(command);
+        }
+        if let Some(hit) = self.projects.first() {
+            return Some(format!(
+                "pb env run --project {} -e {} -- <cmd>",
+                hit.project, hit.env
+            ));
+        }
+        self.suggestions.first().map(|s| {
+            format!(
+                "pb key edit {} --env {}  # then: pb key run {} -- <cmd>",
+                s.entry.id, self.name, s.entry.id
+            )
+        })
+    }
+}
+
+/// The fragments of a variable name that actually identify something.
+fn identifying_tokens(name: &str) -> Vec<String> {
+    name.split('_')
+        .map(|token| token.trim().to_lowercase())
+        .filter(|token| !token.is_empty() && !GENERIC_TOKENS.contains(&token.as_str()))
+        .collect()
+}
+
+/// Entries that look like `name` without carrying it as their `env`.
+///
+/// Two rules, strongest first. A verbatim mention in the purpose, label or id
+/// is near-certain — free-text purposes are exactly where the link used to be
+/// buried ("same value as the GitHub secret NEON_API_KEY"). A token match is
+/// weaker and deliberately conservative: every identifying fragment of the
+/// name has to appear somewhere in the entry, and fragments that identify
+/// nothing ([`GENERIC_TOKENS`]) are dropped first, so `API_KEY` — which is all
+/// generic — suggests nothing at all rather than everything.
+fn suggest_for(name: &str, entries: &[KeyEntry]) -> Vec<Suggestion> {
+    let needle = name.to_lowercase();
+    let tokens = identifying_tokens(name);
+    let mut strong: Vec<Suggestion> = Vec::new();
+    let mut weak: Vec<Suggestion> = Vec::new();
+
+    for entry in entries {
+        let mention = [
+            ("purpose", entry.purpose.as_deref()),
+            ("label", Some(entry.label.as_str())),
+            ("id", Some(entry.id.as_str())),
+        ]
+        .into_iter()
+        .filter_map(|(field, value)| value.map(|value| (field, value)))
+        .find(|(_, value)| value.to_lowercase().contains(&needle));
+
+        if let Some((field, _)) = mention {
+            strong.push(Suggestion {
+                entry: entry.clone(),
+                why: format!("{field} mentions {name}"),
+            });
+            continue;
+        }
+        if tokens.is_empty() {
+            continue;
+        }
+        let haystack = format!(
+            "{} {} {} {}",
+            entry.id,
+            entry.label,
+            entry.provider,
+            entry.purpose.as_deref().unwrap_or_default()
+        )
+        .to_lowercase();
+        if tokens.iter().all(|token| haystack.contains(token.as_str())) {
+            weak.push(Suggestion {
+                entry: entry.clone(),
+                why: format!("matches tokens {}", tokens.join(", ")),
+            });
+        }
+    }
+
+    strong
+        .into_iter()
+        .chain(weak)
+        .take(MAX_SUGGESTIONS)
+        .collect()
+}
+
+/// One wanted name against the two local registries. Pure: the IO happens in
+/// the tool, the judgement happens here, and the judgement is what gets tested.
+fn resolve_one(
+    name: &str,
+    entries: &[KeyEntry],
+    project_vars: &[(String, String, Vec<EnvVarInfo>)],
+) -> ResolvedVar {
+    let name = name.trim().to_string();
+    let keys: Vec<KeyEntry> = entries
+        .iter()
+        .filter(|e| {
+            e.env
+                .as_deref()
+                .is_some_and(|env| env.eq_ignore_ascii_case(&name))
+        })
+        .cloned()
+        .collect();
+    // Suggestions are the consolation prize, never noise on top of an answer.
+    let suggestions = if keys.is_empty() {
+        suggest_for(&name, entries)
+    } else {
+        Vec::new()
+    };
+    let projects: Vec<ProjectHit> = project_vars
+        .iter()
+        .filter_map(|(project, env, vars)| {
+            vars.iter()
+                .find(|var| var.name.eq_ignore_ascii_case(&name))
+                .map(|var| ProjectHit {
+                    project: project.clone(),
+                    env: env.clone(),
+                    source: var.source,
+                })
+        })
+        .collect();
+
+    ResolvedVar {
+        name,
+        keys,
+        suggestions,
+        projects,
+    }
+}
+
+/// The wire shape of one resolved name.
+fn resolved_json(
+    resolved: &ResolvedVar,
+    now: DateTime<Utc>,
+) -> Result<serde_json::Value, ErrorData> {
+    let keys = resolved
+        .keys
+        .iter()
+        .map(|e| describe(e, now))
+        .collect::<Result<Vec<_>, ErrorData>>()?;
+    let suggestions = resolved
+        .suggestions
+        .iter()
+        .map(|s| {
+            Ok(serde_json::json!({
+                "id": s.entry.id,
+                "provider": s.entry.provider,
+                "label": s.entry.label,
+                "env": s.entry.env,
+                "expiry_state": encode(&s.entry.expiry_state(now))?,
+                "why": s.why,
+            }))
+        })
+        .collect::<Result<Vec<_>, ErrorData>>()?;
+    let projects = resolved
+        .projects
+        .iter()
+        .map(|hit| {
+            Ok(serde_json::json!({
+                "project": hit.project,
+                "env": hit.env,
+                "source": encode(&hit.source)?,
+            }))
+        })
+        .collect::<Result<Vec<_>, ErrorData>>()?;
+
+    Ok(serde_json::json!({
+        "name": resolved.name,
+        "status": resolved.status(),
+        "keys": keys,
+        "suggestions": suggestions,
+        "projects": projects,
+        "use": resolved.use_command(),
+    }))
+}
+
 // ---------------------------------------------------------------------------
 // tools
 // ---------------------------------------------------------------------------
@@ -181,12 +548,18 @@ Fill in `purpose` and `expires_at` whenever you know them. They are what make th
 having: `purpose` is what tells the user in six months whether they can revoke it, and \
 `expires_at` is what lets patchbay warn them before a deploy starts failing.
 
+Fill in `env` too: the UPPER_SNAKE_CASE name the value is read under \
+(`CLOUDFLARE_API_TOKEN`, `NEON_API_KEY` — the exact spelling the code, the CI secret or the \
+vendor SDK already uses, otherwise <PROVIDER>_<THING>_<KIND>). It is the only structured link \
+between a slug id and the variable a task is missing, which is what lets the next agent find \
+this key with resolve_env_vars instead of asking the user for a value they already gave you.
+
 Both-or-neither: metadata and value are written together, and a keychain failure rolls the \
 metadata back, so a successful result means the key really is stored. A duplicate id is an error \
 unless you pass overwrite: true.
 
 Returns the stored metadata (id, provider, label, purpose, scopes, created_at, expires_at, \
-last4, source). The secret is never echoed back.")]
+last4, source, env). The secret is never echoed back.")]
     async fn store_key(
         &self,
         peer: Peer<RoleServer>,
@@ -203,7 +576,8 @@ last4, source). The secret is never echoed back.")]
             .purpose(params.purpose)
             .scopes(params.scopes.unwrap_or_default())
             .expires_at(expires_at)
-            .endpoint(params.endpoint);
+            .endpoint(params.endpoint)
+            .env(params.env);
         let secret = params.secret;
         let overwrite = params.overwrite.unwrap_or(false);
 
@@ -215,36 +589,259 @@ last4, source). The secret is never echoed back.")]
     }
 
     #[tool(description = "\
-CHEAP, SAFE. Every standalone API key registered on this machine — metadata only. Reads one \
-local JSON file: no keychain access, no network, no secret values.
+CHEAP, SAFE. LOOK HERE BEFORE SAYING A CREDENTIAL IS MISSING. Every standalone API key \
+registered on this machine — metadata only. Reads one local JSON file: no keychain access, no \
+network, no secret values.
 
 Call this before store_key to see whether the key is already registered and what id convention \
 the user follows, when the user asks what keys or tokens they have, and when something \
 credential-shaped just failed — an expired entry here explains a lot of otherwise mysterious \
 403s.
 
+Narrow it. This machine may hold dozens of entries with long purposes; pass `env` when you know \
+the variable name, `provider` when you know the issuer, `query` for anything else, and only call \
+it bare when the user asks what they have. For 'which of these variables can this machine \
+supply?' prefer resolve_env_vars.
+
 Returns a JSON array of entries: { id, provider, label, purpose, scopes, created_at, \
-expires_at, last4, source, expiry_state }.
+expires_at, last4, source, env, expiry_state }.
 
+- `env` is the environment variable the entry is exposed as (`CLOUDFLARE_API_TOKEN`), when it \
+has one. It is the name code reads the value under, the name `pb key run` injects it as, and the \
+one resolve_env_vars matches on; an entry without it is one to backfill with update_key as soon \
+as you learn the name.
 - `expiry_state` is derived for you: 'expired', 'expiring_soon' (within 30 days), 'valid', or \
 'no_expiry'. Surface anything expired or expiring soon — that is the whole point of the vault.
 - `last4` is the last 4 characters of the secret, so the user can match an entry against a token \
 in a provider's dashboard. It is the only thing here derived from the value.
 - `source` says who registered the entry ('cli', 'mcp:<client>', 'gui').
 - Secret values are NOT included and cannot be obtained from this tool.")]
-    async fn list_keys(&self) -> Result<CallToolResult, ErrorData> {
+    async fn list_keys(
+        &self,
+        Parameters(params): Parameters<ListKeysParams>,
+    ) -> Result<CallToolResult, ErrorData> {
+        // Every field is optional and the struct is `#[serde(default)]`, so a
+        // call with no `arguments` at all — which rmcp hands the extractor as
+        // an empty object — is still the unfiltered listing it always was.
+        let filter = KeyFilter {
+            provider: params.provider,
+            env: params.env,
+            query: params.query,
+        };
         let keys = self.keys.clone();
         match offload(move || keys.list()).await? {
             Ok(entries) => {
                 let now = Utc::now();
-                let described: Result<Vec<_>, ErrorData> =
-                    entries.iter().map(|e| describe(e, now)).collect();
+                let described: Result<Vec<_>, ErrorData> = filter_keys(&entries, &filter)
+                    .iter()
+                    .map(|e| describe(e, now))
+                    .collect();
                 Ok(json_ok(serde_json::Value::Array(described?)))
             }
             Err(err) => Ok(tool_error(err)),
         }
     }
 
+    #[tool(description = "\
+FIX OR COMPLETE A KEY'S METADATA without touching its value. Use it to backfill `env` (the \
+variable name) on an entry that lacks one the moment you learn it — the purpose often says which \
+GitHub secret or `.env` name the value lives under — to correct a purpose or label, or to record \
+an expiry the user just told you.
+
+Not for rotation: a new VALUE is store_key with overwrite: true. Not gated: this reads and \
+writes keys.json only and never opens the keychain.
+
+Pass only the fields you are changing. Each one REPLACES what was there — `scopes` replaces the \
+whole list, `purpose` replaces the whole sentence — so carry over anything worth keeping. To \
+blank a field instead, name it in `clear`: 'purpose', 'expires_at', 'endpoint' and 'env' are the \
+four that can be blanked. Naming a field in `clear` and passing a value for it is an error, and \
+so is a call that changes nothing.
+
+`id`, `created_at` and `last4` never change: they describe the stored value, and a key cannot be \
+renamed. An `env` that is not UPPER_SNAKE_CASE is refused, and the refusal spells the corrected \
+name — use that rather than inventing a variant.
+
+Returns the updated entry: { id, provider, label, purpose, scopes, created_at, expires_at, \
+last4, source, endpoint, env, expiry_state, linked_tool }.")]
+    async fn update_key(
+        &self,
+        Parameters(params): Parameters<UpdateKeyParams>,
+    ) -> Result<CallToolResult, ErrorData> {
+        let cleared = match clear_set(&params.clear.unwrap_or_default()) {
+            Ok(set) => set,
+            Err(message) => return Ok(tool_error(anyhow::anyhow!(message))),
+        };
+        for (field, given) in [
+            ("purpose", params.purpose.is_some()),
+            ("expires_at", params.expires_at.is_some()),
+            ("endpoint", params.endpoint.is_some()),
+            ("env", params.env.is_some()),
+        ] {
+            if given && cleared.contains(field) {
+                return Ok(tool_error(anyhow::anyhow!(
+                    "`{field}` is both set and listed in `clear`; pass one or the other"
+                )));
+            }
+        }
+
+        let mut patch = KeyPatch {
+            provider: params.provider,
+            label: params.label,
+            scopes: params.scopes,
+            ..KeyPatch::default()
+        };
+        if let Some(purpose) = params.purpose {
+            patch.purpose = Some(Some(purpose));
+        } else if cleared.contains("purpose") {
+            patch.purpose = Some(None);
+        }
+        if let Some(raw) = params.expires_at {
+            match parse_expiry(&raw) {
+                Ok(at) => patch.expires_at = Some(Some(at)),
+                Err(message) => return Ok(tool_error(anyhow::anyhow!(message))),
+            }
+        } else if cleared.contains("expires_at") {
+            patch.expires_at = Some(None);
+        }
+        if let Some(endpoint) = params.endpoint {
+            patch.endpoint = Some(Some(endpoint));
+        } else if cleared.contains("endpoint") {
+            patch.endpoint = Some(None);
+        }
+        if let Some(env) = params.env {
+            patch.env = Some(Some(env));
+        } else if cleared.contains("env") {
+            patch.env = Some(None);
+        }
+
+        if patch.is_empty() {
+            return Ok(tool_error(anyhow::anyhow!(
+                "nothing to change: pass at least one field to set, or name one in `clear`"
+            )));
+        }
+
+        let keys = self.keys.clone();
+        let id = params.id;
+        match offload(move || keys.update_metadata(&id, patch)).await? {
+            Ok(entry) => Ok(json_ok(describe(&entry, Utc::now())?)),
+            Err(err) => Ok(tool_error(err)),
+        }
+    }
+
+    #[tool(description = "\
+CHEAP, SAFE. CALL THIS WHEN A TASK NEEDS AN ENVIRONMENT VARIABLE OR CREDENTIAL — before asking \
+the user for a value, before writing a placeholder, before saying it is missing. Give it the \
+names the code reads (`CLOUDFLARE_API_TOKEN`, `DATABASE_URL`) and it answers which of them this \
+machine can already supply: from the key vault (by each entry's `env` name, with best-effort \
+suggestions when nothing is named exactly), and from the env vault's registered projects. Reads \
+two local JSON files; no keychain, no network, no values.
+
+A command that failed with 401/403, a script reading `process.env.X`, a deploy wanting a secret, \
+a blank line in a `.env` — all of them are this call. Pass `project` only when you already know \
+which project's environment to look in; the default searches every registered project and every \
+environment.
+
+Returns { resolved, found, missing, note }. Each entry of `resolved` is { name, status, keys, \
+suggestions, projects, use }:
+
+- `status` is 'key' (a vault entry is named exactly this), 'project_var' (a registered project's \
+environment carries it), 'both', 'suggested' (nothing is named this, but an entry looks like it) \
+or 'missing' (nothing at all).
+- `keys` are full vault entries, metadata only. TWO ENTRIES MAY SHARE ONE NAME — a dev and a \
+production `LANGFUSE_SECRET_KEY` — so when more than one comes back, pick by `purpose` and say \
+which you picked; never guess.
+- `suggestions` appear only when nothing is named exactly, and each carries { id, provider, \
+label, env, expiry_state, why }. A suggestion IS A GUESS: confirm it with the user before using \
+it, and once confirmed, record it with update_key so the next lookup is exact instead of lucky.
+- `projects` are { project, env, source } — which registered project and environment already \
+carry a variable of that name.
+- `use` is the point of the whole answer: THE EXACT COMMAND that puts the value where the task \
+needs it, without you ever seeing it. Relay it, or run it — `pb key run <id> -- <cmd>` injects \
+one vault key as its variable into one child process, `pb env run --project <id> -e <env> -- \
+<cmd>` does the same for a project's whole environment. Do NOT follow up with get_key: the \
+answer here is HOW TO USE the value, and reading it back is both gated and unnecessary.
+- `found` counts the names this machine can supply outright ('key', 'project_var' or 'both'). \
+`missing` lists the names with nothing at all — those, and only those, are the ones to go back \
+to the user about. A 'suggested' name is in neither: it is waiting on a human to confirm.")]
+    async fn resolve_env_vars(
+        &self,
+        Parameters(params): Parameters<ResolveEnvVarsParams>,
+    ) -> Result<CallToolResult, ErrorData> {
+        let names: Vec<String> = params
+            .names
+            .iter()
+            .map(|name| name.trim().to_string())
+            .filter(|name| !name.is_empty())
+            .collect();
+        if names.is_empty() {
+            return Ok(tool_error(anyhow::anyhow!(
+                "pass at least one variable name in `names`, spelled the way the code reads it \
+                 (\"CLOUDFLARE_API_TOKEN\")"
+            )));
+        }
+        if names.len() > MAX_RESOLVE_NAMES {
+            return Ok(tool_error(anyhow::anyhow!(
+                "{} names is more than the {MAX_RESOLVE_NAMES} this tool takes at once; ask for \
+                 the ones the task actually reads",
+                names.len()
+            )));
+        }
+
+        let keys = self.keys.clone();
+        let envs = self.envs.clone();
+        let wanted = params.project;
+        let gathered = offload(move || {
+            let entries = keys.list()?;
+            let mut projects = envs.projects()?;
+            if let Some(want) = &wanted {
+                projects.retain(|p| p.id == *want);
+                if projects.is_empty() {
+                    anyhow::bail!(
+                        "no project registered as `{want}`; list_env_projects shows the ids"
+                    );
+                }
+            }
+            let mut project_vars: Vec<(String, String, Vec<EnvVarInfo>)> = Vec::new();
+            for project in &projects {
+                for env in project.env_names() {
+                    project_vars.push((
+                        project.id.clone(),
+                        env.to_string(),
+                        envs.list(&project.id, env)?,
+                    ));
+                }
+            }
+            Ok::<_, anyhow::Error>((entries, project_vars))
+        })
+        .await?;
+
+        let (entries, project_vars) = match gathered {
+            Ok(pair) => pair,
+            Err(err) => return Ok(tool_error(err)),
+        };
+
+        let now = Utc::now();
+        let resolved: Vec<ResolvedVar> = names
+            .iter()
+            .map(|name| resolve_one(name, &entries, &project_vars))
+            .collect();
+        let found = resolved.iter().filter(|r| r.is_supplied()).count();
+        let missing: Vec<&str> = resolved
+            .iter()
+            .filter(|r| r.status() == "missing")
+            .map(|r| r.name.as_str())
+            .collect();
+        let rendered: Result<Vec<_>, ErrorData> =
+            resolved.iter().map(|r| resolved_json(r, now)).collect();
+
+        Ok(json_ok(serde_json::json!({
+            "resolved": rendered?,
+            "found": found,
+            "missing": missing,
+            "note": RESOLVE_NOTE,
+        })))
+    }
+
     #[tool(description = "\
 ASK THE ISSUER whether a registered key still works. NOT gated: this returns a verdict, never \
 the value, so it is safe to call whenever the answer would change what you do.
@@ -541,4 +1138,352 @@ mod tests {
         assert!(!map.contains_key("secret"));
         assert_eq!(map["last4"], "1234");
     }
+
+    // -----------------------------------------------------------------
+    // resolving a wanted variable name
+    // -----------------------------------------------------------------
+
+    fn key(id: &str, provider: &str, env: Option<&str>, purpose: Option<&str>) -> KeyEntry {
+        KeyEntry {
+            id: id.into(),
+            provider: provider.into(),
+            label: format!("{id} label"),
+            purpose: purpose.map(Into::into),
+            scopes: vec![],
+            created_at: Utc::now(),
+            expires_at: None,
+            last4: "1234".into(),
+            source: "mcp:test".into(),
+            endpoint: None,
+            env: env.map(Into::into),
+        }
+    }
+
+    fn project(id: &str, env: &str, names: &[&str]) -> (String, String, Vec<EnvVarInfo>) {
+        (
+            id.into(),
+            env.into(),
+            names
+                .iter()
+                .map(|name| EnvVarInfo {
+                    name: (*name).into(),
+                    source: EnvVarSource::Synced,
+                })
+                .collect(),
+        )
+    }
+
+    #[test]
+    fn test_an_exact_env_name_resolves_to_the_key_and_a_run_command() {
+        let entries = vec![key(
+            "cf-gh-actions-deploy",
+            "cloudflare",
+            Some("CLOUDFLARE_API_TOKEN"),
+            None,
+        )];
+        let resolved = resolve_one("CLOUDFLARE_API_TOKEN", &entries, &[]);
+
+        assert_eq!(resolved.status(), "key");
+        assert_eq!(resolved.keys.len(), 1);
+        assert!(resolved.suggestions.is_empty(), "{resolved:?}");
+        assert_eq!(
+            resolved.use_command().unwrap(),
+            "pb key run cf-gh-actions-deploy -- <cmd>"
+        );
+    }
+
+    #[test]
+    fn test_two_keys_under_one_name_both_come_back_and_the_command_names_the_others() {
+        let entries = vec![
+            key(
+                "langfuse-dev",
+                "langfuse",
+                Some("LANGFUSE_SECRET_KEY"),
+                None,
+            ),
+            key(
+                "langfuse-prod",
+                "langfuse",
+                Some("LANGFUSE_SECRET_KEY"),
+                None,
+            ),
+        ];
+        let resolved = resolve_one("LANGFUSE_SECRET_KEY", &entries, &[]);
+
+        assert_eq!(resolved.keys.len(), 2);
+        assert_eq!(
+            resolved.use_command().unwrap(),
+            "pb key run langfuse-dev -- <cmd>  # or: langfuse-prod"
+        );
+    }
+
+    #[test]
+    fn test_the_match_is_case_insensitive_on_both_sides() {
+        let entries = vec![key("neon", "neon", Some("NEON_API_KEY"), None)];
+        assert_eq!(
+            resolve_one("neon_api_key", &entries, &[]).status(),
+            "key",
+            "a lowercase spelling still finds the entry"
+        );
+
+        let vars = [project("pathors", "prod", &["database_url"])];
+        assert_eq!(
+            resolve_one("DATABASE_URL", &[], &vars).status(),
+            "project_var"
+        );
+    }
+
+    #[test]
+    fn test_a_purpose_that_mentions_the_name_becomes_a_suggestion() {
+        let entries = vec![key(
+            "neon-api",
+            "neon",
+            None,
+            Some("also stored as the GitHub secret NEON_API_KEY"),
+        )];
+        let resolved = resolve_one("NEON_API_KEY", &entries, &[]);
+
+        assert_eq!(resolved.status(), "suggested");
+        assert!(!resolved.is_supplied());
+        assert_eq!(resolved.suggestions.len(), 1);
+        assert_eq!(resolved.suggestions[0].why, "purpose mentions NEON_API_KEY");
+        assert_eq!(
+            resolved.use_command().unwrap(),
+            "pb key edit neon-api --env NEON_API_KEY  # then: pb key run neon-api -- <cmd>"
+        );
+    }
+
+    #[test]
+    fn test_the_identifying_tokens_of_a_name_find_an_entry_that_never_says_it() {
+        let entries = vec![key(
+            "neon-prod",
+            "neon",
+            None,
+            Some("the production Postgres branch"),
+        )];
+        let resolved = resolve_one("NEON_API_KEY", &entries, &[]);
+
+        assert_eq!(resolved.status(), "suggested");
+        assert_eq!(resolved.suggestions[0].why, "matches tokens neon");
+    }
+
+    #[test]
+    fn test_a_name_made_only_of_generic_tokens_suggests_nothing() {
+        // `API_KEY` is every second entry in the vault. Suggesting all of them
+        // is worse than suggesting none, so the generic tokens are dropped and
+        // an empty token list skips the weak rule entirely.
+        assert!(identifying_tokens("API_KEY").is_empty());
+        assert_eq!(identifying_tokens("NEON_API_KEY"), vec!["neon"]);
+        assert_eq!(
+            identifying_tokens("APPLE_ASC_ISSUER_ID"),
+            vec!["apple", "asc", "issuer"]
+        );
+
+        let entries = vec![
+            key("neon-prod", "neon", None, Some("the production key")),
+            key("cf-deploy", "cloudflare", None, Some("a deploy token")),
+        ];
+        let resolved = resolve_one("API_KEY", &entries, &[]);
+        assert_eq!(resolved.status(), "missing");
+        assert!(resolved.suggestions.is_empty(), "{resolved:?}");
+    }
+
+    #[test]
+    fn test_suggestions_are_capped_and_strong_matches_come_first() {
+        let mut entries: Vec<KeyEntry> = (0..8)
+            .map(|i| key(&format!("neon-{i}"), "neon", None, Some("a neon thing")))
+            .collect();
+        entries.push(key(
+            "the-one",
+            "other",
+            None,
+            Some("this is the NEON_API_KEY value"),
+        ));
+        let resolved = resolve_one("NEON_API_KEY", &entries, &[]);
+
+        assert_eq!(resolved.suggestions.len(), MAX_SUGGESTIONS);
+        assert_eq!(resolved.suggestions[0].entry.id, "the-one");
+    }
+
+    #[test]
+    fn test_a_project_environment_that_carries_the_name_is_a_hit() {
+        let vars = [
+            project("pathors", "dev", &["OTHER"]),
+            project("pathors", "prod", &["DATABASE_URL", "OTHER"]),
+        ];
+        let resolved = resolve_one("DATABASE_URL", &[], &vars);
+
+        assert_eq!(resolved.status(), "project_var");
+        assert!(resolved.is_supplied());
+        assert_eq!(resolved.projects.len(), 1);
+        assert_eq!(resolved.projects[0].project, "pathors");
+        assert_eq!(resolved.projects[0].env, "prod");
+        assert_eq!(
+            resolved.use_command().unwrap(),
+            "pb env run --project pathors -e prod -- <cmd>"
+        );
+    }
+
+    #[test]
+    fn test_a_key_and_a_project_variable_are_both_reported_and_the_key_wins_the_command() {
+        let entries = vec![key("neon", "neon", Some("DATABASE_URL"), None)];
+        let vars = [project("pathors", "prod", &["DATABASE_URL"])];
+        let resolved = resolve_one("DATABASE_URL", &entries, &vars);
+
+        assert_eq!(resolved.status(), "both");
+        assert_eq!(resolved.use_command().unwrap(), "pb key run neon -- <cmd>");
+    }
+
+    #[test]
+    fn test_a_name_nothing_matches_is_missing_with_no_command() {
+        let entries = vec![key("cf", "cloudflare", Some("CLOUDFLARE_API_TOKEN"), None)];
+        let resolved = resolve_one("STRIPE_SECRET_KEY", &entries, &[]);
+
+        assert_eq!(resolved.status(), "missing");
+        assert!(resolved.use_command().is_none());
+        assert!(!resolved.is_supplied());
+    }
+
+    #[test]
+    fn test_a_resolved_name_renders_without_a_secret_and_keeps_the_use_command() {
+        let entries = vec![key("neon", "neon", Some("NEON_API_KEY"), None)];
+        let value = resolved_json(&resolve_one("NEON_API_KEY", &entries, &[]), Utc::now()).unwrap();
+
+        assert_eq!(value["status"], "key");
+        assert_eq!(value["use"], "pb key run neon -- <cmd>");
+        assert_eq!(value["keys"][0]["id"], "neon");
+        assert_eq!(value["keys"][0]["env"], "NEON_API_KEY");
+        assert!(value["keys"][0].get("secret").is_none());
+    }
+
+    // -----------------------------------------------------------------
+    // parameters and descriptions
+    // -----------------------------------------------------------------
+
+    #[test]
+    fn test_list_keys_still_works_with_no_arguments_at_all() {
+        // rmcp hands the extractor `arguments.unwrap_or_default()`, i.e. an
+        // empty object, when a call carries no arguments. `#[serde(default)]`
+        // on the struct is what keeps that a valid, unfiltered call.
+        let params: ListKeysParams = serde_json::from_value(serde_json::json!({})).unwrap();
+        assert!(params.provider.is_none());
+        assert!(params.env.is_none());
+        assert!(params.query.is_none());
+
+        let filter = KeyFilter {
+            provider: params.provider,
+            env: params.env,
+            query: params.query,
+        };
+        assert!(filter.is_empty());
+    }
+
+    #[test]
+    fn test_only_the_nullable_fields_can_be_cleared() {
+        let clear = |fields: &[&str]| {
+            clear_set(&fields.iter().map(|f| (*f).to_string()).collect::<Vec<_>>())
+        };
+
+        let ok = clear(&["env", "PURPOSE", " expires_at "]).unwrap();
+        assert!(ok.contains("env"));
+        assert!(ok.contains("purpose"));
+        assert!(ok.contains("expires_at"));
+        assert!(clear(&[]).unwrap().is_empty());
+
+        let err = clear(&["label"]).unwrap_err();
+        assert!(err.contains("cannot clear `label`"), "{err}");
+        for field in CLEARABLE_FIELDS {
+            assert!(err.contains(field), "{err}");
+        }
+        assert!(clear(&["id"]).is_err());
+    }
+
+    #[test]
+    fn test_store_key_asks_for_the_variable_name() {
+        let tools = PatchbayServer::keys_router().list_all();
+        let store = tools
+            .iter()
+            .find(|t| t.name == "store_key")
+            .expect("store_key is missing from the router");
+        let text = store.description.as_deref().unwrap_or_default().to_string();
+
+        assert!(text.contains("`env`"), "{text}");
+        assert!(text.contains("CLOUDFLARE_API_TOKEN"), "{text}");
+        assert!(text.contains("resolve_env_vars"), "{text}");
+    }
+
+    #[test]
+    fn test_list_keys_leads_with_the_lookup_and_teaches_the_filters() {
+        let tools = PatchbayServer::keys_router().list_all();
+        let list = tools
+            .iter()
+            .find(|t| t.name == "list_keys")
+            .expect("list_keys is missing from the router");
+        let text = list.description.as_deref().unwrap_or_default().to_string();
+
+        assert!(
+            text.starts_with("CHEAP, SAFE. LOOK HERE BEFORE SAYING A CREDENTIAL IS MISSING."),
+            "{text}"
+        );
+        assert!(text.contains("Narrow it."), "{text}");
+        assert!(text.contains("resolve_env_vars"), "{text}");
+        assert!(text.contains("Secret values are NOT included"), "{text}");
+    }
+
+    #[test]
+    fn test_update_key_is_advertised_as_metadata_only_and_ungated() {
+        let tools = PatchbayServer::keys_router().list_all();
+        let update = tools
+            .iter()
+            .find(|t| t.name == "update_key")
+            .expect("update_key is missing from the router");
+        let text = update
+            .description
+            .as_deref()
+            .unwrap_or_default()
+            .to_string();
+
+        assert!(text.contains("without touching its value"), "{text}");
+        assert!(text.contains("backfill `env`"), "{text}");
+        assert!(text.contains("Not for rotation"), "{text}");
+        assert!(text.contains("Not gated"), "{text}");
+        assert!(text.contains("never opens the keychain"), "{text}");
+    }
+
+    #[test]
+    fn test_resolve_env_vars_is_the_call_before_asking_the_user() {
+        let tools = PatchbayServer::keys_router().list_all();
+        let resolve = tools
+            .iter()
+            .find(|t| t.name == "resolve_env_vars")
+            .expect("resolve_env_vars is missing from the router");
+        let text = resolve
+            .description
+            .as_deref()
+            .unwrap_or_default()
+            .to_string();
+
+        assert!(
+            text.contains("before asking \nthe user for a value")
+                || text.contains("before asking the user for a value"),
+            "{text}"
+        );
+        assert!(text.contains("before writing a placeholder"), "{text}");
+        assert!(text.contains("pb key run"), "{text}");
+        assert!(text.contains("pb env run"), "{text}");
+        assert!(
+            text.contains("do NOT follow up with get_key")
+                || text.contains("Do NOT follow up with get_key"),
+            "{text}"
+        );
+        assert!(text.contains("A suggestion IS A GUESS"), "{text}");
+    }
+
+    #[test]
+    fn test_the_resolve_note_never_stops_saying_where_the_value_goes() {
+        assert!(RESOLVE_NOTE.contains("Values are never returned"));
+        assert!(RESOLVE_NOTE.contains("pb key run"));
+        assert!(RESOLVE_NOTE.contains("pb env run"));
+        assert!(RESOLVE_NOTE.contains("update_key"));
+    }
 }
diff --git a/crates/patchbay-mcp/src/server.rs b/crates/patchbay-mcp/src/server.rs
index 5676cb5..da8d632 100644
--- a/crates/patchbay-mcp/src/server.rs
+++ b/crates/patchbay-mcp/src/server.rs
@@ -31,7 +31,8 @@ use serde::Deserialize;
 /// here as well as on the individual tools.
 const INSTRUCTIONS: &str = "\
 patchbay reports and switches the active login of the developer CLIs on this machine \
-(gcloud, aws, gh, kubectl, az, wrangler, rclone, infisical).
+(gcloud, aws, gh, kubectl, az, wrangler, rclone, infisical), and is the machine's vault for the \
+API keys, tokens and project environment variables no CLI tracks.
 
 Read this before using the tools.
 
@@ -84,9 +85,9 @@ like bugs from the inside, and patchbay already knows about the ones it ships.
 6. Every connection tool returns metadata about credentials. Token, secret and key values are \
 never returned by them.
 
-7. The key vault (`store_key`, `list_keys`, `get_key`, `remove_key`) is a different thing from \
-the connection tools above: it is this machine's registry for standalone API keys and tokens \
-that no CLI tracks. `store_key` is the one you should reach for unprompted — whenever you create \
+7. The key vault (`store_key`, `list_keys`, `update_key`, `resolve_env_vars`, `get_key`, \
+`remove_key`) is a different thing from the connection tools above: it is this machine's \
+registry for standalone API keys and tokens that no CLI tracks. `store_key` is the one you should reach for unprompted — whenever you create \
 or receive a long-lived API key or token during a task, register it, so the user's patchbay \
 stays the source of truth. Secrets go into the OS keychain; only the last 4 characters are \
 written to disk. Never echo a secret anywhere else.
@@ -118,7 +119,39 @@ application config, which is the failure mode this rule exists to prevent.
    Unsure? Ask which project the value is scoped to. If the answer is 'all of them' or 'it is \
 mine', it is a patchbay key.
 
-10. The MCP client tools (`list_mcp_clients`, `add_mcp_server`, `copy_mcp_server`, \
+10. LOOK HERE BEFORE ASKING FOR A CREDENTIAL. When a task needs an API key, token, database URL, \
+issuer id or any other environment variable — a command fails with 401/403, a script reads \
+`process.env.X`, a deploy wants a secret, a `.env` has a blank line — do not ask the user for the \
+value, do not write a placeholder, and do not say it is missing until you have checked this \
+machine: call `resolve_env_vars` with the variable names the task reads (or `list_keys` with \
+`env`/`query`, or `list_env_vars` for a registered project). Most credentials the user has ever \
+handled are already here, with a purpose that says what they open. The answer is never the value; \
+it is HOW TO USE IT without seeing it: `pb key run <id> -- <cmd>` injects a vault key as its \
+variable into one child process, and `pb env run` does the same for a project's whole \
+environment. Run those through the shell — the secret goes from the keychain to the child process \
+and never through the conversation. Only when nothing matches do you ask the user, and when they \
+then hand you a value, register it (`store_key`, with `env`) so the next agent does not have to \
+ask.
+
+11. NAME THE VARIABLE. Every key has an optional `env`: the environment variable it is exposed \
+as, in UPPER_SNAKE_CASE. Fill it on `store_key`, and backfill it with `update_key` the moment you \
+learn the name for an entry that lacks one (the purpose often says: 'same value as GitHub secret \
+NEON_API_KEY'). The rules:
+   - Use the name code already reads. If the repo, the CI secret or the vendor SDK spells it \
+`CLOUDFLARE_API_TOKEN`, that is the name — not a synonym, not a nicer one.
+   - Otherwise `<PROVIDER>_<THING>_<KIND>`: the issuer first, what it is, then the kind of \
+credential — `CLOUDFLARE_API_TOKEN`, `NEON_API_KEY`, `APPLE_ASC_ISSUER_ID`, \
+`GITHUB_APP_PRIVATE_KEY`, `LANGFUSE_SECRET_KEY`, `R2_SECRET_ACCESS_KEY`. Kinds: `_API_KEY`, \
+`_API_TOKEN`, `_SECRET`, `_SECRET_KEY`, `_PRIVATE_KEY`, `_PASSWORD`, `_ID`, `_URL` (a \
+`DATABASE_URL` is a credential too).
+   - Letters, digits and `_` only; starts with a letter; at most 64 characters. `cf-token`, \
+`cloudflareToken` and `CF TOKEN` are refused, and the refusal spells the corrected name.
+   - Two keys may share a name (a dev and a production `LANGFUSE_SECRET_KEY`); the id and purpose \
+tell them apart, and `resolve_env_vars` returns both so you pick by purpose, never by guessing.
+   - The `id` stays the lowercase slug it always was (`<provider>-<thing>[-<scope>]`); `env` is \
+the second name for the same entry, and it is the one code searches by.
+
+12. The MCP client tools (`list_mcp_clients`, `add_mcp_server`, `copy_mcp_server`, \
 `remove_mcp_server`) are a third thing again: they read and edit the config files in which the AI \
 clients on this machine — Claude Code, Claude Desktop, Cursor, Codex, Windsurf, VS Code — register \
 their MCP servers. `list_mcp_clients` is cheap and safe. The other three modify another tool's \
@@ -127,7 +160,7 @@ is needed. Confirm with the user before removing anything. Never write a secret
 `env` or `headers` through these tools: those land in a plain-text config file. Reference an \
 environment variable name, or register the secret with `store_key`, instead.
 
-11. `plan_setup` and `mark_setup_done` are the fourth thing again: the checklist for finishing a \
+13. `plan_setup` and `mark_setup_done` are the fourth thing again: the checklist for finishing a \
 MOVE to a new machine, after `pb export` / `pb import` have carried whatever could be carried. \
 Work the list one item at a time; run only the items whose `auto` is true; hand every \
 `needs_browser` item to the human with the exact command rather than trying to drive a browser \
@@ -135,7 +168,7 @@ login yourself; and re-check with `mark_setup_done` after each one, because patc
 tool instead of believing what you report. Stop when `complete` is true, and do not invent extra \
 setup work.
 
-12. The project env vault (`list_env_projects`, `list_env_vars`, `pull_env`, `set_env_var`) is a \
+14. The project env vault (`list_env_projects`, `list_env_vars`, `pull_env`, `set_env_var`) is a \
 fifth thing: the environment variables one PROJECT needs, per environment, in two \
 layers — `synced` (a local mirror of that project's remote secret manager, refreshed wholesale \
 only by `pull_env`) and `local` (set on this machine, never pushed anywhere, and it WINS over a \
@@ -620,3 +653,35 @@ impl ServerHandler for PatchbayServer {
         std::borrow::Cow::Borrowed(ProtocolVersion::KNOWN_VERSIONS)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_the_instructions_teach_the_lookup_before_the_ask() {
+        // The instructions are the only thing an agent reads before it has
+        // called anything, so the rule that stops it inventing a placeholder
+        // for a credential this machine already holds has to survive edits.
+        assert!(INSTRUCTIONS.contains("LOOK HERE BEFORE ASKING FOR A CREDENTIAL"));
+        assert!(INSTRUCTIONS.contains("NAME THE VARIABLE"));
+        assert!(INSTRUCTIONS.contains("<PROVIDER>_<THING>_<KIND>"));
+        assert!(INSTRUCTIONS.contains("pb key run"));
+        assert!(INSTRUCTIONS.contains("resolve_env_vars"));
+        assert!(INSTRUCTIONS.contains("update_key"));
+    }
+
+    #[test]
+    fn test_the_rules_are_numbered_once_each() {
+        // Two rules were inserted after rule 9, which renumbered everything
+        // after them; a duplicate number is the failure that produces.
+        for n in 1..=14 {
+            let marker = format!("\n{n}. ");
+            assert_eq!(
+                INSTRUCTIONS.matches(&marker).count(),
+                1,
+                "rule {n} does not appear exactly once"
+            );
+        }
+    }
+}
diff --git a/docs/env-vault.md b/docs/env-vault.md
index 58ea94a..dde2799 100644
--- a/docs/env-vault.md
+++ b/docs/env-vault.md
@@ -305,6 +305,21 @@ inside single quotes is valid shell, but it would split the variable across two
 lines and every line-based reader of a `.env` file would then read it wrong.
 Output from `pb env export` parses back through `pb env import` unchanged.
 
+Two commands read values *here*. The [key vault](key-vault.md) has its own, and
+the distinction is which question you are asking. `pb env run` is for a
+project's whole environment — everything this directory needs, merged across
+the synced and local layers. `pb key run <id>... -- <cmd>` is for one credential
+of yours that belongs to no project: the Cloudflare token a deploy script wants,
+the Neon key a one-off migration needs. Same guarantee on both — the values go
+into one child process and nowhere else.
+
+Which side holds a given name is not something you should have to remember, and
+an agent has no way to know at all. The MCP tool `resolve_env_vars` answers it:
+give it the variable names the code reads and it says, per name, which vault
+entries carry that `env`, which env-vault environments define it, and the exact
+`pb key run` or `pb env run` that supplies it. Names and commands only — it
+returns no value, which is why it needs no gate.
+
 ### Coming from a .env file
 
 ```sh
diff --git a/docs/key-vault.md b/docs/key-vault.md
index 8aa03cd..2bddbc9 100644
--- a/docs/key-vault.md
+++ b/docs/key-vault.md
@@ -11,15 +11,21 @@ no idea they were there.
 # The secret is read from stdin, or from a hidden prompt. Never from argv.
 pbpaste | pb key add cf-gh-actions-deploy \
   --provider cloudflare \
+  --env CLOUDFLARE_API_TOKEN \
   --label "CF deploy token" \
   --purpose "deploy worker from GitHub Actions in pathorsAI/patchbay" \
   --scopes workers:edit,zone:read \
   --expires 2027-01-01
 
-pb key list                 # id, provider, label, last4, expiry, purpose
+pb key list                 # id, provider, env, label, last4, expiry, purpose
 pb key list --expiring 30   # what dies in the next month
+pb key list --env CLOUDFLARE_API_TOKEN   # who holds the name code reads
+pb key list --provider cloudflare        # everything from one issuer
+pb key list --grep deploy                # id, label, purpose, provider, env
 pb key list --json          # what the MCP server and the panel see
+pb key edit cf-gh-actions-deploy --env CLOUDFLARE_API_TOKEN  # metadata only
 pb key copy cf-gh-actions-deploy    # to the clipboard, never to your terminal
+pb key run  cf-gh-actions-deploy -- wrangler deploy  # into a child process
 pb key verify cf-gh-actions-deploy  # ask Cloudflare whether it still works
 pb key rm  cf-gh-actions-deploy     # metadata and Keychain item, both
 ```
@@ -27,15 +33,121 @@ pb key rm  cf-gh-actions-deploy     # metadata and Keychain item, both
 ### In the panel
 
 The vault view browses the same registry, and writes to it: **add key** opens a
-form — id, provider, label, a masked secret field, and the optional purpose,
-scopes, expiry and endpoint behind a fold — and each row has a trash affordance
-with an inline confirm. Both go through the same `KeyRegistry` calls as `pb key
-add` and `pb key rm`, so the rules and the error messages are identical.
+form — id, env, provider, label, a masked secret field, and the optional
+purpose, scopes, expiry and endpoint behind a fold — and each row has a trash
+affordance with an inline confirm. Both go through the same `KeyRegistry` calls
+as `pb key add` and `pb key rm`, so the rules and the error messages are
+identical. The table shows the env name in its own column, next to the provider.
 
 The panel takes a secret; it never gives one back. There is no reveal, no copy,
-and no command behind the window that returns a value — `pb key copy <id>` is
-still the only way out. See the security model below for why the asymmetry
-survives a GUI intact.
+and no command behind the window that returns a value — the two ways out are
+both in the CLI, `pb key copy <id>` and `pb key run <id> -- <cmd>`. See the
+security model below for why the asymmetry survives a GUI intact.
+
+### The second name: env
+
+An entry's `id` is a lowercase slug: `cf-gh-actions-deploy`. The name code
+reads is something else entirely: `CLOUDFLARE_API_TOKEN`. Nothing connected the
+two. Whoever needed the token — a script, a CI job, an agent working in this
+repo — had to already know that the Cloudflare token lives under an id built
+out of "gh actions" and "deploy", which is not a thing you can guess and not a
+thing you can search for. The mapping did exist, as prose, buried in a
+`--purpose` string. Prose is not an index.
+
+`--env` makes it a field:
+
+```sh
+pb key add cf-gh-actions-deploy --env CLOUDFLARE_API_TOKEN --provider cloudflare
+pb key list --env CLOUDFLARE_API_TOKEN     # who holds it
+pb key run  cf-gh-actions-deploy -- wrangler deploy   # use it under that name
+```
+
+The name is validated on the way in: A–Z, digits and `_`, starting with a
+letter, at most 64 characters — the shape a shell and every dotenv parser will
+actually accept. A refusal spells out the corrected name rather than restating
+the rule, so `cf-token` comes back as "env names are UPPER_SNAKE_CASE (the shape
+code reads them in); try `CF_TOKEN`" and the fix is a copy-paste.
+
+It is **optional**, and deliberately so. An Apple issuer id or a D-U-N-S number
+belongs in the vault as an index entry — something you will need and would
+otherwise have to go looking for — but it is not a variable any program reads,
+and inventing a name for it would be inventing a fact. Leave it off.
+
+**Two entries may share a name.** A dev and a production `LANGFUSE_SECRET_KEY`
+are two different secrets that code reads under one identifier; that is the
+normal shape, not a conflict, so nothing refuses it and a lookup returns both.
+The `id` stays unique and stays the thing you name in a command.
+
+#### Naming convention
+
+Use **the name code already reads**. If the repo, the CI secret or the vendor's
+own SDK spells it `CLOUDFLARE_API_TOKEN`, that is the name — patchbay's job is
+to be findable by what already exists, not to impose a taxonomy on it. Only
+when nothing has named it yet do you compose one, as
+`<PROVIDER>_<THING>_<KIND>`: who issued it, what it is, what kind of thing it
+is.
+
+| Name | Why |
+|---|---|
+| `CLOUDFLARE_API_TOKEN` | what wrangler and Cloudflare's own docs read |
+| `NEON_API_KEY` | provider, then kind; nothing in between to say |
+| `APPLE_ASC_ISSUER_ID` | provider, the thing (App Store Connect), the kind |
+| `GITHUB_APP_PRIVATE_KEY` | the app's key, not the user's — `THING` disambiguates |
+| `LANGFUSE_SECRET_KEY` | pairs with `LANGFUSE_PUBLIC_KEY`; the kind carries the difference |
+| `R2_SECRET_ACCESS_KEY` | the S3-compatible name R2 clients already expect |
+
+The kinds: `_API_KEY`, `_API_TOKEN`, `_SECRET`, `_SECRET_KEY`, `_PRIVATE_KEY`,
+`_PASSWORD`, `_ID`, `_URL`.
+
+#### Backfilling
+
+Every key registered before this field existed has no name, and the vault is
+worth exactly as much as the fraction of it that is findable. `pb key edit`
+fixes that without going near the keychain:
+
+```sh
+pb key edit cf-gh-actions-deploy --env CLOUDFLARE_API_TOKEN
+pb key edit neon-api --env NEON_API_KEY --purpose "prod branch migrations"
+pb key edit old-thing --no-env
+```
+
+`edit` is metadata only — it never opens the keychain, never touches the
+value, and cannot rotate anything. Rotation stays `pb key add --overwrite`,
+where a secret is actually being handled. The flags mirror `add`'s —
+`--provider`, `--label`, `--purpose`, `--scopes`, `--expires`, `--endpoint`,
+`--env` — and the four nullable ones have a clearing form: `--no-purpose`,
+`--no-expires`, `--no-endpoint`, `--no-env`. `id`, `last4` and the registration
+date are not editable, because they describe the value in the keychain and
+editing them here would only make the registry lie about it.
+
+### Using a key without seeing it
+
+A vault an agent cannot use is a vault an agent will work around. `pb key copy`
+was the only way a value came out, and it goes to the clipboard — fine for a
+human pasting into a browser, useless to a process, and not something an agent
+should be doing at all.
+
+```sh
+pb key run cf-gh-actions-deploy -- wrangler deploy
+pb key run neon-api langfuse-prod -- bun run migrate
+pb key run --as CF_TOKEN=cf-gh-actions-deploy -- ./deploy.sh
+```
+
+`run` looks each id up, reads its value from the keychain, and starts the
+command with those variables added to the environment it inherits. The value
+goes keychain → child process and touches nothing else: not stdout, not a log,
+not argv, not a file, and not the context of whatever model asked for it.
+stderr names the variables and the ids it filled them from, so you can see what
+was injected without seeing what was injected.
+
+An id with no `env` name and no `--as` is refused, naming the id and the
+`pb key edit <id> --env NAME` that fixes it — a run that silently dropped a
+credential would fail somewhere much less obvious.
+
+This is the second way a value leaves the vault, and the two are for different
+people. `pb key copy` is for a human with a browser tab open. `pb key run` is
+for everything else, and it is the path an agent should take: the answer to
+"I need `CLOUDFLARE_API_TOKEN`" is a command to run, not a value to read.
 
 ### Verification
 
@@ -122,9 +234,10 @@ security find-generic-password -s patchbay -a cf-gh-actions-deploy
 second; if the Keychain refuses, the metadata file is restored to exactly what
 it was. The registry never advertises a key whose value was never stored.
 
-**Writing is easy, reading is not.** There is no `pb key show`. `pb key copy`
-pipes the value into `pbcopy` — it never passes through stdout, a log or your
-shell history.
+**Writing is easy, reading is not.** There is no `pb key show`. Two commands
+read a value and they are the only two. `pb key copy` pipes it into `pbcopy`;
+`pb key run` puts it in one child process's environment. Neither passes it
+through stdout, a log, argv or your shell history, and neither prints it.
 
 **Why the CLI reads stdin.** A secret passed as an argument is not private:
 argv is world-readable through `ps` for the length of the process, and your
@@ -144,8 +257,11 @@ value, never copies one, and has no command wired up that could return one.
 
 | Tool | Gate |
 |---|---|
-| `store_key` | open — this is the point. An agent that creates a key registers it, with purpose and expiry, so your patchbay stays the source of truth |
-| `list_keys` | open — metadata only, plus a derived `expiry_state` |
+| `store_key` | open — this is the point. An agent that creates a key registers it, with `env`, purpose and expiry, so your patchbay stays the source of truth |
+| `list_keys` | open — metadata only, plus a derived `expiry_state`. Takes `provider`, `env` and `query` filters, so an agent narrows the vault instead of reading all of it |
+| `update_key` | open — metadata only. It cannot reach the keychain and cannot rotate anything, so backfilling an `env` name or fixing a purpose needs no gate |
+| `resolve_env_vars` | open — variable names in, names and commands out. Never a value |
+| `verify_key` | open — a verdict carries nothing to leak |
 | `get_key` | **refused** unless the server process has `PATCHBAY_ALLOW_SECRET_READ=1` |
 | `remove_key` | **refused** unless the same flag is set — it is destructive |
 
@@ -160,6 +276,28 @@ human at `pb key copy <id>` instead. If you do want an agent reading values:
 } } }
 ```
 
+**What the agent is told to do with all this.** A gate an agent never reaches
+is not protecting anything, and for a long time that was the actual situation:
+a vault with sixty-five keys in it, on a machine where the agent working in
+your repo asked *you* for `CLOUDFLARE_API_TOKEN`, wrote a `<your-token-here>`
+placeholder, or reported the variable as missing. It was not refused. It never
+looked. So the server's instructions now carry two rules:
+
+- **Look here before asking for a credential.** Before asking the human,
+  writing a placeholder or calling something missing, call `resolve_env_vars`
+  with the variable names the code reads. It answers per name: which vault
+  entries carry that `env`, which env-vault projects define it, `suggestions`
+  when nothing matches exactly (entries whose purpose, label or id mention the
+  name or its distinctive words), a `status` — `key`, `project_var`, `both`,
+  `suggested` or `missing` — and a `use` string: the exact `pb key run …` or
+  `pb env run …` to put the value where the code will find it. It reads two
+  local JSON files and returns **no secret value**, which is why it is
+  ungated. The answer to "I need this credential" is a command, not a value.
+- **Name the variable.** Register with `env` set, following the convention
+  above, and backfill entries that lack one with `update_key`. An entry with no
+  variable name is invisible to the lookup that would have found it, which is
+  how a vault full of the right keys ends up being worked around.
+
 **Known tradeoff.** The Keychain write shells out to `security
 add-generic-password -w <value>`, which puts the secret in that command's argv
 for the few milliseconds it runs — visible to `ps` for the same user. `security`

From 8ec4b1dd9a91174e7606a8b17fed5c193e0c4d91 Mon Sep 17 00:00:00 2001
From: YJack0000 <jack@pathors.com>
Date: Tue, 8 Sep 2026 00:43:31 +0800
Subject: [PATCH 3/3] [refactor] split pb key run() and update_key patch
 building so each function stays under Sonar's complexity ceiling

---
 crates/patchbay-cli/src/keys.rs | 879 +++++++++++++++++++-------------
 crates/patchbay-mcp/src/keys.rs | 170 ++++--
 2 files changed, 645 insertions(+), 404 deletions(-)

diff --git a/crates/patchbay-cli/src/keys.rs b/crates/patchbay-cli/src/keys.rs
index 085fccb..ea6fc5b 100644
--- a/crates/patchbay-cli/src/keys.rs
+++ b/crates/patchbay-cli/src/keys.rs
@@ -15,7 +15,7 @@ use std::process::{Command as Process, Stdio};
 
 use anyhow::{Context, Result};
 use chrono::{DateTime, NaiveDate, NaiveTime, TimeZone, Utc};
-use clap::Subcommand;
+use clap::{Args, Subcommand};
 use patchbay_core::keys::{
     expiring_within_at, filter_keys, validate_env_name, KeyEntry, KeyFilter, KeyPatch, KeyRegistry,
     NewKey,
@@ -45,96 +45,15 @@ pub enum Command {
     ///
     /// The secret is read from stdin when something is piped in, and from a
     /// hidden prompt otherwise. It is never taken as an argument.
-    Add {
-        /// Lowercase slug, unique in the vault, e.g. `cf-gh-actions-deploy`.
-        id: String,
-        /// Who issued it: `cloudflare`, `github`, `openai`, … Free-form.
-        #[arg(long)]
-        provider: Option<String>,
-        /// Display name. Defaults to the id.
-        #[arg(long)]
-        label: Option<String>,
-        /// What it is for, e.g. "deploy from GitHub Actions in repo X".
-        #[arg(long)]
-        purpose: Option<String>,
-        /// Granted scopes, comma-separated.
-        #[arg(long, value_delimiter = ',')]
-        scopes: Vec<String>,
-        /// Expiry: `2027-01-01`, or a full RFC 3339 timestamp.
-        #[arg(long, value_name = "DATE")]
-        expires: Option<String>,
-        /// Instance URL, for providers with more than one address —
-        /// `https://<you>.grafana.net`. Grafana needs it to verify.
-        #[arg(long, value_name = "URL")]
-        endpoint: Option<String>,
-        /// Environment variable the key is exposed as, UPPER_SNAKE_CASE:
-        /// `CLOUDFLARE_API_TOKEN`. What `pb key run` injects it as, and what an
-        /// agent looks it up by.
-        #[arg(long, value_name = "NAME")]
-        env: Option<String>,
-        /// Replace an existing entry with the same id (a rotation).
-        #[arg(long)]
-        overwrite: bool,
-    },
+    Add(AddArgs),
     /// List registered keys. Metadata only — never values.
-    List {
-        #[arg(long)]
-        json: bool,
-        /// Only keys expiring within this many days (already-expired included).
-        #[arg(long, value_name = "DAYS")]
-        expiring: Option<i64>,
-        /// Only keys from this issuer.
-        #[arg(long, value_name = "P")]
-        provider: Option<String>,
-        /// Only the key(s) exposed as this variable name.
-        #[arg(long, value_name = "NAME")]
-        env: Option<String>,
-        /// Free text over id, label, provider, purpose and variable name.
-        #[arg(long, value_name = "TEXT")]
-        grep: Option<String>,
-    },
+    List(ListArgs),
     /// Change a key's metadata. The stored value is never touched.
     ///
     /// Every `--no-*` clears its field. `id`, `last4` and the registration date
     /// are not editable: they describe the value in the keychain, and editing
     /// them here would only make the registry lie about it.
-    Edit {
-        /// The key to edit.
-        id: String,
-        /// Who issued it: `cloudflare`, `github`, `openai`, … Free-form.
-        #[arg(long)]
-        provider: Option<String>,
-        /// Display name.
-        #[arg(long)]
-        label: Option<String>,
-        /// What it is for, e.g. "deploy from GitHub Actions in repo X".
-        #[arg(long, conflicts_with = "no_purpose")]
-        purpose: Option<String>,
-        /// Forget what this key is for.
-        #[arg(long = "no-purpose")]
-        no_purpose: bool,
-        /// Replace the recorded scopes, comma-separated.
-        #[arg(long, value_delimiter = ',')]
-        scopes: Vec<String>,
-        /// Expiry: `2027-01-01`, or a full RFC 3339 timestamp.
-        #[arg(long, value_name = "DATE", conflicts_with = "no_expires")]
-        expires: Option<String>,
-        /// Forget the expiry.
-        #[arg(long = "no-expires")]
-        no_expires: bool,
-        /// Instance URL, for providers with more than one address.
-        #[arg(long, value_name = "URL", conflicts_with = "no_endpoint")]
-        endpoint: Option<String>,
-        /// Forget the instance URL.
-        #[arg(long = "no-endpoint")]
-        no_endpoint: bool,
-        /// Environment variable the key is exposed as, UPPER_SNAKE_CASE.
-        #[arg(long, value_name = "NAME", conflicts_with = "no_env")]
-        env: Option<String>,
-        /// Forget the variable name.
-        #[arg(long = "no-env")]
-        no_env: bool,
-    },
+    Edit(EditArgs),
     /// Put a key's value on the clipboard, without printing it.
     Copy { id: String },
     /// Run a command with keys in its environment.
@@ -178,296 +97,321 @@ pub enum Command {
     },
 }
 
-/// Returns the process exit code.
-pub fn run(command: Command, styles: &Styles) -> Result<i32> {
-    let registry = KeyRegistry::detect()?;
-
-    match command {
-        Command::Add {
-            id,
-            provider,
-            label,
-            purpose,
-            scopes,
-            expires,
-            endpoint,
-            env,
-            overwrite,
-        } => {
-            let expires_at = expires.as_deref().map(parse_expiry).transpose()?;
-            let new = NewKey::new(&id, "cli")
-                .provider(provider.clone().unwrap_or_else(|| "unknown".to_string()))
-                .label(label.unwrap_or_else(|| id.clone()))
-                .purpose(purpose)
-                .scopes(scopes)
-                .expires_at(expires_at)
-                .endpoint(endpoint)
-                .env(env);
-
-            let secret = read_secret(&id)?;
-            let entry = registry.add(new, &secret, overwrite)?;
-            drop(secret);
-
-            println!("registered {} (…{})", entry.id, entry.last4);
-            if let Some(endpoint) = &entry.endpoint {
-                println!("  instance: {endpoint}");
-            }
-            if let Some(name) = &entry.env {
-                println!("  env:      {name}");
-            }
-            println!("  value:    {}", registry.store_name());
-            println!("  metadata: {}", registry.path().display());
-            if provider.is_none() {
-                println!("  hint: --provider makes the board far easier to scan");
-            }
-            if entry.expires_at.is_none() {
-                println!("  hint: --expires lets patchbay warn you before it dies");
-            }
-            if entry.env.is_none() {
-                println!(
-                    "  hint: --env NAME lets `pb key run` and agents find it by the name code reads"
-                );
-            }
-            Ok(0)
-        }
+/// Everything `pb key add` takes. The secret is deliberately absent: it is
+/// read from stdin or a hidden prompt, never from argv.
+#[derive(Args, Debug)]
+pub struct AddArgs {
+    /// Lowercase slug, unique in the vault, e.g. `cf-gh-actions-deploy`.
+    id: String,
+    /// Who issued it: `cloudflare`, `github`, `openai`, … Free-form.
+    #[arg(long)]
+    provider: Option<String>,
+    /// Display name. Defaults to the id.
+    #[arg(long)]
+    label: Option<String>,
+    /// What it is for, e.g. "deploy from GitHub Actions in repo X".
+    #[arg(long)]
+    purpose: Option<String>,
+    /// Granted scopes, comma-separated.
+    #[arg(long, value_delimiter = ',')]
+    scopes: Vec<String>,
+    /// Expiry: `2027-01-01`, or a full RFC 3339 timestamp.
+    #[arg(long, value_name = "DATE")]
+    expires: Option<String>,
+    /// Instance URL, for providers with more than one address —
+    /// `https://<you>.grafana.net`. Grafana needs it to verify.
+    #[arg(long, value_name = "URL")]
+    endpoint: Option<String>,
+    /// Environment variable the key is exposed as, UPPER_SNAKE_CASE:
+    /// `CLOUDFLARE_API_TOKEN`. What `pb key run` injects it as, and what an
+    /// agent looks it up by.
+    #[arg(long, value_name = "NAME")]
+    env: Option<String>,
+    /// Replace an existing entry with the same id (a rotation).
+    #[arg(long)]
+    overwrite: bool,
+}
 
-        Command::List {
-            json,
-            expiring,
-            provider,
-            env,
-            grep,
-        } => {
-            let filter = KeyFilter {
-                provider,
-                env,
-                query: grep,
-            };
-            let mut entries = registry.list()?;
-            if let Some(days) = expiring {
-                entries = expiring_within_at(&entries, Utc::now(), days);
-            }
-            // After the expiring cut, so the two narrow the same listing rather
-            // than fighting over it.
-            entries = filter_keys(&entries, &filter);
-
-            if json {
-                // Machine-readable: JSON only, no ANSI, no extras.
-                println!("{}", serde_json::to_string_pretty(&entries)?);
-                return Ok(0);
-            }
-            if entries.is_empty() {
-                let active = active_filters(expiring, &filter);
-                if active.is_empty() {
-                    println!("no keys registered yet");
-                    println!("  pb key add <id> --provider <who> --label \"<what>\"");
-                } else if filter.is_empty() {
-                    // The expiring-only question deserves its own sentence: an
-                    // empty answer there is good news, not a failed search.
-                    println!(
-                        "no registered key expires within {}d",
-                        expiring.unwrap_or_default()
-                    );
-                } else {
-                    println!("no registered key matches");
-                    println!("  filters: {}", active.join(", "));
-                }
-                return Ok(0);
-            }
-            print!("{}", render_table(&entries, Utc::now(), styles));
-            Ok(0)
-        }
+/// The listing's output mode and the filters that narrow it.
+#[derive(Args, Debug)]
+pub struct ListArgs {
+    #[arg(long)]
+    json: bool,
+    /// Only keys expiring within this many days (already-expired included).
+    #[arg(long, value_name = "DAYS")]
+    expiring: Option<i64>,
+    /// Only keys from this issuer.
+    #[arg(long, value_name = "P")]
+    provider: Option<String>,
+    /// Only the key(s) exposed as this variable name.
+    #[arg(long, value_name = "NAME")]
+    env: Option<String>,
+    /// Free text over id, label, provider, purpose and variable name.
+    #[arg(long, value_name = "TEXT")]
+    grep: Option<String>,
+}
 
-        Command::Edit {
-            id,
-            provider,
-            label,
-            purpose,
-            no_purpose,
-            scopes,
-            expires,
-            no_expires,
-            endpoint,
-            no_endpoint,
-            env,
-            no_env,
-        } => {
-            let mut patch = KeyPatch::default();
-            let mut touched: Vec<Field> = Vec::new();
-
-            if let Some(provider) = provider {
-                patch.provider = Some(provider);
-                touched.push(Field::Provider);
-            }
-            if let Some(label) = label {
-                patch.label = Some(label);
-                touched.push(Field::Label);
-            }
-            if no_purpose || purpose.is_some() {
-                patch.purpose = Some(purpose);
-                touched.push(Field::Purpose);
-            }
-            if !scopes.is_empty() {
-                patch.scopes = Some(scopes);
-                touched.push(Field::Scopes);
-            }
-            if no_expires || expires.is_some() {
-                patch.expires_at = Some(expires.as_deref().map(parse_expiry).transpose()?);
-                touched.push(Field::Expires);
-            }
-            if no_endpoint || endpoint.is_some() {
-                patch.endpoint = Some(endpoint);
-                touched.push(Field::Endpoint);
-            }
-            if no_env || env.is_some() {
-                patch.env = Some(env);
-                touched.push(Field::Env);
-            }
-            if patch.is_empty() {
-                anyhow::bail!(
-                    "nothing to change; pass at least one of --provider, --label, --purpose, \
-                     --scopes, --expires, --endpoint, --env (or a --no-* to clear one)"
-                );
-            }
+/// Which key to edit, and what to make of it.
+#[derive(Args, Debug)]
+pub struct EditArgs {
+    /// The key to edit.
+    id: String,
+    #[command(flatten)]
+    fields: EditFields,
+}
 
-            // A rejected name (`pb key edit x --env cf_token`) surfaces the
-            // core's error verbatim: it already suggests the right spelling.
-            let updated = registry.update_metadata(&id, patch)?;
-            println!("updated {}", updated.id);
-            for field in touched {
-                let name = format!("{}:", field.label());
-                println!("  {name:<FIELD_COL$} {}", field.value(&updated));
-            }
-            Ok(0)
-        }
+/// The editable half of `pb key edit`, split out so the patch it describes can
+/// be built — and tested — without a vault to write it to.
+#[derive(Args, Debug)]
+pub struct EditFields {
+    /// Who issued it: `cloudflare`, `github`, `openai`, … Free-form.
+    #[arg(long)]
+    provider: Option<String>,
+    /// Display name.
+    #[arg(long)]
+    label: Option<String>,
+    /// What it is for, e.g. "deploy from GitHub Actions in repo X".
+    #[arg(long, conflicts_with = "no_purpose")]
+    purpose: Option<String>,
+    /// Forget what this key is for.
+    #[arg(long = "no-purpose")]
+    no_purpose: bool,
+    /// Replace the recorded scopes, comma-separated.
+    #[arg(long, value_delimiter = ',')]
+    scopes: Vec<String>,
+    /// Expiry: `2027-01-01`, or a full RFC 3339 timestamp.
+    #[arg(long, value_name = "DATE", conflicts_with = "no_expires")]
+    expires: Option<String>,
+    /// Forget the expiry.
+    #[arg(long = "no-expires")]
+    no_expires: bool,
+    /// Instance URL, for providers with more than one address.
+    #[arg(long, value_name = "URL", conflicts_with = "no_endpoint")]
+    endpoint: Option<String>,
+    /// Forget the instance URL.
+    #[arg(long = "no-endpoint")]
+    no_endpoint: bool,
+    /// Environment variable the key is exposed as, UPPER_SNAKE_CASE.
+    #[arg(long, value_name = "NAME", conflicts_with = "no_env")]
+    env: Option<String>,
+    /// Forget the variable name.
+    #[arg(long = "no-env")]
+    no_env: bool,
+}
 
-        Command::Copy { id } => {
-            let entry = registry
-                .get(&id)?
-                .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
-            let secret = registry.get_secret(&id)?;
-            to_clipboard(&secret)?;
-            drop(secret);
-            println!("copied {} (…{}) to the clipboard", entry.id, entry.last4);
-            println!("  it stays there until you copy something else — paste it and move on");
-            Ok(0)
-        }
+/// Returns the process exit code.
+pub fn run(command: Command, styles: &Styles) -> Result<i32> {
+    let registry = KeyRegistry::detect()?;
 
+    match command {
+        Command::Add(args) => add(&registry, args),
+        Command::List(args) => list(&registry, args, styles),
+        Command::Edit(args) => edit(&registry, args),
+        Command::Copy { id } => copy(&registry, &id),
         Command::Run {
             keys,
             aliases,
             command,
-        } => {
-            let (bin, args) = command
-                .split_first()
-                .ok_or_else(|| anyhow::anyhow!("nothing to run; pass a command after `--`"))?;
-            let aliases = parse_aliases(&aliases)?;
-
-            // Everything is resolved before anything is spawned: a typo has to
-            // fail here, not halfway through a deploy.
-            let mut entries: Vec<KeyEntry> = Vec::new();
-            for id in keys.iter().chain(aliases.iter().map(|(_, id)| id)) {
-                if entries.iter().any(|e| &e.id == id) {
-                    continue;
-                }
-                entries.push(
-                    registry
-                        .get(id)?
-                        .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?,
-                );
-            }
-            let plan = injection_plan(&entries, &keys, &aliases)?;
-
-            // stderr, so a command whose stdout is being piped stays clean —
-            // and names only, never a value or a fragment of one.
-            let named: Vec<String> = plan
-                .iter()
-                .map(|(name, id)| format!("{name} ({id})"))
-                .collect();
-            eprintln!("injecting {} into `{bin}`", named.join(", "));
-
-            let mut child = std::process::Command::new(bin);
-            child.args(args);
-            // The parent environment is inherited on purpose: unlike
-            // `pb env run`, this adds a few credentials to an otherwise normal
-            // shell rather than defining the whole environment.
-            for (name, id) in &plan {
-                let secret = registry.get_secret(id)?;
-                child.env(name, &secret);
-                drop(secret);
-            }
-            let status = child
-                .status()
-                .with_context(|| format!("could not run `{bin}`"))?;
-
-            match status.code() {
-                Some(code) => Ok(code),
-                None => {
-                    eprintln!("pb: `{bin}` was killed by a signal");
-                    Ok(1)
-                }
-            }
-        }
-
+        } => run_command(&registry, &keys, &aliases, &command),
         Command::Verify {
             id,
             json,
             no_update,
-        } => {
-            let entry = registry
-                .get(&id)?
-                .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
-            // The secret lives for exactly this call and is never printed.
-            let secret = registry.get_secret(&id)?;
-            let outcome = verify_key(&entry, &secret);
-            drop(secret);
-
-            let updated = if no_update {
-                Vec::new()
-            } else {
-                absorb(&registry, &entry, &outcome)?
-            };
-
-            if json {
-                let mut value = serde_json::to_value(&outcome)?;
-                if let Some(map) = value.as_object_mut() {
-                    map.insert("id".into(), entry.id.clone().into());
-                    map.insert("provider".into(), entry.provider.clone().into());
-                    map.insert("metadata_updated".into(), updated.clone().into());
-                }
-                println!("{}", serde_json::to_string_pretty(&value)?);
-            } else {
-                print_verify(&entry, &outcome, &updated, styles);
-            }
-            Ok(match outcome.status {
-                KeyVerifyStatus::Valid | KeyVerifyStatus::Unsupported => 0,
-                KeyVerifyStatus::Invalid | KeyVerifyStatus::Expired => 1,
-                // Distinct from 1: nothing was learned about the key.
-                KeyVerifyStatus::Unreachable => 2,
-            })
-        }
+        } => verify(&registry, &id, json, no_update, styles),
+        Command::Rm { id, yes } => rm(&registry, &id, yes),
+    }
+}
 
-        Command::Rm { id, yes } => {
-            let entry = registry
-                .get(&id)?
-                .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
-            if !yes && !confirm(&entry)? {
-                println!("left {} alone", entry.id);
-                return Ok(0);
-            }
-            let removed = registry.remove(&id)?;
-            println!("removed {} (…{})", removed.id, removed.last4);
-            println!("  the value is gone from the {}", registry.store_name());
-            println!("  revoke it at the provider too — patchbay only forgets it");
-            Ok(0)
+// ---------------------------------------------------------------------------
+// add
+// ---------------------------------------------------------------------------
+
+/// `pb key add` — register a key and hand its value to the keychain.
+fn add(registry: &KeyRegistry, args: AddArgs) -> Result<i32> {
+    let AddArgs {
+        id,
+        provider,
+        label,
+        purpose,
+        scopes,
+        expires,
+        endpoint,
+        env,
+        overwrite,
+    } = args;
+
+    let expires_at = expires.as_deref().map(parse_expiry).transpose()?;
+    let new = NewKey::new(&id, "cli")
+        .provider(provider.clone().unwrap_or_else(|| "unknown".to_string()))
+        .label(label.unwrap_or_else(|| id.clone()))
+        .purpose(purpose)
+        .scopes(scopes)
+        .expires_at(expires_at)
+        .endpoint(endpoint)
+        .env(env);
+
+    let secret = read_secret(&id)?;
+    let entry = registry.add(new, &secret, overwrite)?;
+    drop(secret);
+
+    println!("registered {} (…{})", entry.id, entry.last4);
+    if let Some(endpoint) = &entry.endpoint {
+        println!("  instance: {endpoint}");
+    }
+    if let Some(name) = &entry.env {
+        println!("  env:      {name}");
+    }
+    println!("  value:    {}", registry.store_name());
+    println!("  metadata: {}", registry.path().display());
+    if provider.is_none() {
+        println!("  hint: --provider makes the board far easier to scan");
+    }
+    if entry.expires_at.is_none() {
+        println!("  hint: --expires lets patchbay warn you before it dies");
+    }
+    if entry.env.is_none() {
+        println!("  hint: --env NAME lets `pb key run` and agents find it by the name code reads");
+    }
+    Ok(0)
+}
+
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+
+/// `pb key list` — the board, or the same rows as JSON.
+fn list(registry: &KeyRegistry, args: ListArgs, styles: &Styles) -> Result<i32> {
+    let ListArgs {
+        json,
+        expiring,
+        provider,
+        env,
+        grep,
+    } = args;
+
+    let filter = KeyFilter {
+        provider,
+        env,
+        query: grep,
+    };
+    let mut entries = registry.list()?;
+    if let Some(days) = expiring {
+        entries = expiring_within_at(&entries, Utc::now(), days);
+    }
+    // After the expiring cut, so the two narrow the same listing rather
+    // than fighting over it.
+    entries = filter_keys(&entries, &filter);
+
+    if json {
+        // Machine-readable: JSON only, no ANSI, no extras.
+        println!("{}", serde_json::to_string_pretty(&entries)?);
+        return Ok(0);
+    }
+    if entries.is_empty() {
+        let active = active_filters(expiring, &filter);
+        if active.is_empty() {
+            println!("no keys registered yet");
+            println!("  pb key add <id> --provider <who> --label \"<what>\"");
+        } else if filter.is_empty() {
+            // The expiring-only question deserves its own sentence: an
+            // empty answer there is good news, not a failed search.
+            println!(
+                "no registered key expires within {}d",
+                expiring.unwrap_or_default()
+            );
+        } else {
+            println!("no registered key matches");
+            println!("  filters: {}", active.join(", "));
         }
+        return Ok(0);
+    }
+    print!("{}", render_table(&entries, Utc::now(), styles));
+    Ok(0)
+}
+
+// ---------------------------------------------------------------------------
+// copy
+// ---------------------------------------------------------------------------
+
+/// `pb key copy` — keychain → clipboard, with the value never touching stdout.
+fn copy(registry: &KeyRegistry, id: &str) -> Result<i32> {
+    let entry = registry
+        .get(id)?
+        .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
+    let secret = registry.get_secret(id)?;
+    to_clipboard(&secret)?;
+    drop(secret);
+    println!("copied {} (…{}) to the clipboard", entry.id, entry.last4);
+    println!("  it stays there until you copy something else — paste it and move on");
+    Ok(0)
+}
+
+// ---------------------------------------------------------------------------
+// rm
+// ---------------------------------------------------------------------------
+
+/// `pb key rm` — drop the metadata entry and the keychain item together.
+fn rm(registry: &KeyRegistry, id: &str, yes: bool) -> Result<i32> {
+    let entry = registry
+        .get(id)?
+        .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
+    if !yes && !confirm(&entry)? {
+        println!("left {} alone", entry.id);
+        return Ok(0);
     }
+    let removed = registry.remove(id)?;
+    println!("removed {} (…{})", removed.id, removed.last4);
+    println!("  the value is gone from the {}", registry.store_name());
+    println!("  revoke it at the provider too — patchbay only forgets it");
+    Ok(0)
 }
 
 // ---------------------------------------------------------------------------
 // verify
 // ---------------------------------------------------------------------------
 
+/// `pb key verify` — ask the issuer, then report (and usually record) what it
+/// said. Returns the exit code the subcommand's own docs promise.
+fn verify(
+    registry: &KeyRegistry,
+    id: &str,
+    json: bool,
+    no_update: bool,
+    styles: &Styles,
+) -> Result<i32> {
+    let entry = registry
+        .get(id)?
+        .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?;
+    // The secret lives for exactly this call and is never printed.
+    let secret = registry.get_secret(id)?;
+    let outcome = verify_key(&entry, &secret);
+    drop(secret);
+
+    let updated = if no_update {
+        Vec::new()
+    } else {
+        absorb(registry, &entry, &outcome)?
+    };
+
+    if json {
+        let mut value = serde_json::to_value(&outcome)?;
+        if let Some(map) = value.as_object_mut() {
+            map.insert("id".into(), entry.id.clone().into());
+            map.insert("provider".into(), entry.provider.clone().into());
+            map.insert("metadata_updated".into(), updated.clone().into());
+        }
+        println!("{}", serde_json::to_string_pretty(&value)?);
+    } else {
+        print_verify(&entry, &outcome, &updated, styles);
+    }
+    Ok(match outcome.status {
+        KeyVerifyStatus::Valid | KeyVerifyStatus::Unsupported => 0,
+        KeyVerifyStatus::Invalid | KeyVerifyStatus::Expired => 1,
+        // Distinct from 1: nothing was learned about the key.
+        KeyVerifyStatus::Unreachable => 2,
+    })
+}
+
 /// Write back what the issuer just told us, and report what changed.
 ///
 /// The provider is the authority on its own token, so a confirmed expiry or
@@ -546,6 +490,84 @@ fn print_verify(entry: &KeyEntry, outcome: &KeyVerifyOutcome, updated: &[String]
 // edit
 // ---------------------------------------------------------------------------
 
+/// `pb key edit` — apply a metadata patch, then read the stored entry back to
+/// report what actually landed.
+fn edit(registry: &KeyRegistry, args: EditArgs) -> Result<i32> {
+    let EditArgs { id, fields } = args;
+    let (patch, touched) = build_patch(fields)?;
+
+    // A rejected name (`pb key edit x --env cf_token`) surfaces the
+    // core's error verbatim: it already suggests the right spelling.
+    let updated = registry.update_metadata(&id, patch)?;
+    println!("updated {}", updated.id);
+    for field in touched {
+        let name = format!("{}:", field.label());
+        println!("  {name:<FIELD_COL$} {}", field.value(&updated));
+    }
+    Ok(0)
+}
+
+/// The patch a set of `pb key edit` flags describes, and the fields it touches
+/// — in the order they are reported. `Some(None)` is a deliberate clear, a
+/// missing entry is "leave it alone", and an edit that would change nothing is
+/// refused rather than written.
+///
+/// Pure, so every flag combination can be checked without a vault.
+fn build_patch(fields: EditFields) -> Result<(KeyPatch, Vec<Field>)> {
+    let EditFields {
+        provider,
+        label,
+        purpose,
+        no_purpose,
+        scopes,
+        expires,
+        no_expires,
+        endpoint,
+        no_endpoint,
+        env,
+        no_env,
+    } = fields;
+
+    let mut patch = KeyPatch::default();
+    let mut touched: Vec<Field> = Vec::new();
+
+    if let Some(provider) = provider {
+        patch.provider = Some(provider);
+        touched.push(Field::Provider);
+    }
+    if let Some(label) = label {
+        patch.label = Some(label);
+        touched.push(Field::Label);
+    }
+    if no_purpose || purpose.is_some() {
+        patch.purpose = Some(purpose);
+        touched.push(Field::Purpose);
+    }
+    if !scopes.is_empty() {
+        patch.scopes = Some(scopes);
+        touched.push(Field::Scopes);
+    }
+    if no_expires || expires.is_some() {
+        patch.expires_at = Some(expires.as_deref().map(parse_expiry).transpose()?);
+        touched.push(Field::Expires);
+    }
+    if no_endpoint || endpoint.is_some() {
+        patch.endpoint = Some(endpoint);
+        touched.push(Field::Endpoint);
+    }
+    if no_env || env.is_some() {
+        patch.env = Some(env);
+        touched.push(Field::Env);
+    }
+    if patch.is_empty() {
+        anyhow::bail!(
+            "nothing to change; pass at least one of --provider, --label, --purpose, \
+             --scopes, --expires, --endpoint, --env (or a --no-* to clear one)"
+        );
+    }
+    Ok((patch, touched))
+}
+
 /// An editable metadata field, so `pb key edit` can report what it changed by
 /// reading the *stored* entry back rather than echoing what was typed —
 /// trimming and normalization happen in the core, and the report should show
@@ -618,6 +640,65 @@ fn active_filters(expiring: Option<i64>, filter: &KeyFilter) -> Vec<String> {
 // run
 // ---------------------------------------------------------------------------
 
+/// `pb key run` — resolve every requested key, then hand the values to a child
+/// process's environment and nowhere else.
+fn run_command(
+    registry: &KeyRegistry,
+    keys: &[String],
+    aliases: &[String],
+    command: &[String],
+) -> Result<i32> {
+    let (bin, args) = command
+        .split_first()
+        .ok_or_else(|| anyhow::anyhow!("nothing to run; pass a command after `--`"))?;
+    let aliases = parse_aliases(aliases)?;
+
+    // Everything is resolved before anything is spawned: a typo has to
+    // fail here, not halfway through a deploy.
+    let mut entries: Vec<KeyEntry> = Vec::new();
+    for id in keys.iter().chain(aliases.iter().map(|(_, id)| id)) {
+        if entries.iter().any(|e| &e.id == id) {
+            continue;
+        }
+        entries.push(
+            registry
+                .get(id)?
+                .ok_or_else(|| anyhow::anyhow!("no key registered as `{id}`"))?,
+        );
+    }
+    let plan = injection_plan(&entries, keys, &aliases)?;
+
+    // stderr, so a command whose stdout is being piped stays clean —
+    // and names only, never a value or a fragment of one.
+    let named: Vec<String> = plan
+        .iter()
+        .map(|(name, id)| format!("{name} ({id})"))
+        .collect();
+    eprintln!("injecting {} into `{bin}`", named.join(", "));
+
+    let mut child = std::process::Command::new(bin);
+    child.args(args);
+    // The parent environment is inherited on purpose: unlike
+    // `pb env run`, this adds a few credentials to an otherwise normal
+    // shell rather than defining the whole environment.
+    for (name, id) in &plan {
+        let secret = registry.get_secret(id)?;
+        child.env(name, &secret);
+        drop(secret);
+    }
+    let status = child
+        .status()
+        .with_context(|| format!("could not run `{bin}`"))?;
+
+    match status.code() {
+        Some(code) => Ok(code),
+        None => {
+            eprintln!("pb: `{bin}` was killed by a signal");
+            Ok(1)
+        }
+    }
+}
+
 /// `NAME=ID`, split on the first `=` so a key id containing one is still
 /// readable. The name is held to the same shape a stored one is: an alias is a
 /// variable name too, and a run is no excuse to invent a second spelling.
@@ -1307,4 +1388,96 @@ mod tests {
         let err = parse_expiry("next tuesday").unwrap_err().to_string();
         assert!(err.contains("2027-01-01"), "{err}");
     }
+
+    /// No flags at all: every field left alone.
+    fn untouched() -> EditFields {
+        EditFields {
+            provider: None,
+            label: None,
+            purpose: None,
+            no_purpose: false,
+            scopes: Vec::new(),
+            expires: None,
+            no_expires: false,
+            endpoint: None,
+            no_endpoint: false,
+            env: None,
+            no_env: false,
+        }
+    }
+
+    #[test]
+    fn test_build_patch_sets_only_the_fields_that_were_given() {
+        let (patch, touched) = build_patch(EditFields {
+            provider: Some("cloudflare".into()),
+            scopes: vec!["workers:edit".into()],
+            expires: Some("2027-01-01".into()),
+            ..untouched()
+        })
+        .unwrap();
+
+        assert_eq!(patch.provider.as_deref(), Some("cloudflare"));
+        assert_eq!(
+            patch.scopes.as_deref(),
+            Some(&["workers:edit".to_string()][..])
+        );
+        assert_eq!(
+            patch.expires_at,
+            Some(Some(
+                DateTime::parse_from_rfc3339("2027-01-01T00:00:00Z")
+                    .unwrap()
+                    .with_timezone(&Utc)
+            ))
+        );
+        // Untouched fields stay absent, so update_metadata leaves them alone.
+        assert!(patch.label.is_none());
+        assert!(patch.purpose.is_none());
+        assert!(patch.endpoint.is_none());
+        assert!(patch.env.is_none());
+        // Reported in the order the report prints them.
+        assert_eq!(
+            touched,
+            vec![Field::Provider, Field::Scopes, Field::Expires]
+        );
+    }
+
+    #[test]
+    fn test_build_patch_distinguishes_clearing_from_leaving_alone() {
+        let (patch, touched) = build_patch(EditFields {
+            no_purpose: true,
+            no_expires: true,
+            no_endpoint: true,
+            no_env: true,
+            ..untouched()
+        })
+        .unwrap();
+
+        // `Some(None)` is the clear; a missing entry would be "leave it".
+        assert_eq!(patch.purpose, Some(None));
+        assert_eq!(patch.expires_at, Some(None));
+        assert_eq!(patch.endpoint, Some(None));
+        assert_eq!(patch.env, Some(None));
+        assert_eq!(
+            touched,
+            vec![Field::Purpose, Field::Expires, Field::Endpoint, Field::Env]
+        );
+    }
+
+    #[test]
+    fn test_build_patch_refuses_an_edit_that_changes_nothing() {
+        let err = build_patch(untouched()).unwrap_err().to_string();
+        assert!(err.contains("nothing to change"), "{err}");
+        assert!(err.contains("--provider"), "{err}");
+    }
+
+    #[test]
+    fn test_build_patch_rejects_an_unparseable_expiry() {
+        let err = build_patch(EditFields {
+            expires: Some("next tuesday".into()),
+            ..untouched()
+        })
+        .unwrap_err()
+        .to_string();
+        assert!(err.contains("2027-01-01"), "{err}");
+    }
 }
diff --git a/crates/patchbay-mcp/src/keys.rs b/crates/patchbay-mcp/src/keys.rs
index e5ebb08..fdbd261 100644
--- a/crates/patchbay-mcp/src/keys.rs
+++ b/crates/patchbay-mcp/src/keys.rs
@@ -277,6 +277,52 @@ fn clear_set(clear: &[String]) -> Result<BTreeSet<String>, String> {
     Ok(out)
 }
 
+/// A patch field that can be set, blanked, or left alone: `Some(Some(v))`
+/// sets, `Some(None)` blanks, `None` leaves it as it is.
+fn nullable<T>(given: Option<T>, cleared: bool) -> Option<Option<T>> {
+    match (given, cleared) {
+        (Some(value), _) => Some(Some(value)),
+        (None, true) => Some(None),
+        (None, false) => None,
+    }
+}
+
+/// Turns an `update_key` request into the patch it describes, or into the
+/// message explaining why it is not a patch at all.
+fn build_patch(params: UpdateKeyParams) -> Result<KeyPatch, String> {
+    let cleared = clear_set(&params.clear.unwrap_or_default())?;
+    for (field, given) in [
+        ("purpose", params.purpose.is_some()),
+        ("expires_at", params.expires_at.is_some()),
+        ("endpoint", params.endpoint.is_some()),
+        ("env", params.env.is_some()),
+    ] {
+        if given && cleared.contains(field) {
+            return Err(format!(
+                "`{field}` is both set and listed in `clear`; pass one or the other"
+            ));
+        }
+    }
+
+    let expires_at = params.expires_at.as_deref().map(parse_expiry).transpose()?;
+    let patch = KeyPatch {
+        provider: params.provider,
+        label: params.label,
+        scopes: params.scopes,
+        purpose: nullable(params.purpose, cleared.contains("purpose")),
+        expires_at: nullable(expires_at, cleared.contains("expires_at")),
+        endpoint: nullable(params.endpoint, cleared.contains("endpoint")),
+        env: nullable(params.env, cleared.contains("env")),
+    };
+
+    if patch.is_empty() {
+        return Err(
+            "nothing to change: pass at least one field to set, or name one in `clear`".to_string(),
+        );
+    }
+    Ok(patch)
+}
+
 /// An entry that looks like a wanted name without being named it, plus the
 /// reason it was offered — a suggestion the caller cannot explain is one they
 /// cannot confirm with the user.
@@ -667,61 +713,13 @@ last4, source, endpoint, env, expiry_state, linked_tool }.")]
         &self,
         Parameters(params): Parameters<UpdateKeyParams>,
     ) -> Result<CallToolResult, ErrorData> {
-        let cleared = match clear_set(&params.clear.unwrap_or_default()) {
-            Ok(set) => set,
+        let id = params.id.clone();
+        let patch = match build_patch(params) {
+            Ok(patch) => patch,
             Err(message) => return Ok(tool_error(anyhow::anyhow!(message))),
         };
-        for (field, given) in [
-            ("purpose", params.purpose.is_some()),
-            ("expires_at", params.expires_at.is_some()),
-            ("endpoint", params.endpoint.is_some()),
-            ("env", params.env.is_some()),
-        ] {
-            if given && cleared.contains(field) {
-                return Ok(tool_error(anyhow::anyhow!(
-                    "`{field}` is both set and listed in `clear`; pass one or the other"
-                )));
-            }
-        }
-
-        let mut patch = KeyPatch {
-            provider: params.provider,
-            label: params.label,
-            scopes: params.scopes,
-            ..KeyPatch::default()
-        };
-        if let Some(purpose) = params.purpose {
-            patch.purpose = Some(Some(purpose));
-        } else if cleared.contains("purpose") {
-            patch.purpose = Some(None);
-        }
-        if let Some(raw) = params.expires_at {
-            match parse_expiry(&raw) {
-                Ok(at) => patch.expires_at = Some(Some(at)),
-                Err(message) => return Ok(tool_error(anyhow::anyhow!(message))),
-            }
-        } else if cleared.contains("expires_at") {
-            patch.expires_at = Some(None);
-        }
-        if let Some(endpoint) = params.endpoint {
-            patch.endpoint = Some(Some(endpoint));
-        } else if cleared.contains("endpoint") {
-            patch.endpoint = Some(None);
-        }
-        if let Some(env) = params.env {
-            patch.env = Some(Some(env));
-        } else if cleared.contains("env") {
-            patch.env = Some(None);
-        }
-
-        if patch.is_empty() {
-            return Ok(tool_error(anyhow::anyhow!(
-                "nothing to change: pass at least one field to set, or name one in `clear`"
-            )));
-        }
 
         let keys = self.keys.clone();
-        let id = params.id;
         match offload(move || keys.update_metadata(&id, patch)).await? {
             Ok(entry) => Ok(json_ok(describe(&entry, Utc::now())?)),
             Err(err) => Ok(tool_error(err)),
@@ -1486,4 +1484,74 @@ mod tests {
         assert!(RESOLVE_NOTE.contains("pb env run"));
         assert!(RESOLVE_NOTE.contains("update_key"));
     }
+    fn update_params(id: &str) -> UpdateKeyParams {
+        UpdateKeyParams {
+            id: id.to_string(),
+            provider: None,
+            label: None,
+            purpose: None,
+            scopes: None,
+            expires_at: None,
+            endpoint: None,
+            env: None,
+            clear: None,
+        }
+    }
+
+    #[test]
+    fn test_build_patch_sets_one_field_and_leaves_the_rest_alone() {
+        let mut params = update_params("cf-api");
+        params.env = Some("CLOUDFLARE_API_TOKEN".to_string());
+        let patch = build_patch(params).expect("a set is a patch");
+        assert_eq!(patch.env, Some(Some("CLOUDFLARE_API_TOKEN".to_string())));
+        assert_eq!(patch.purpose, None);
+        assert_eq!(patch.expires_at, None);
+        assert_eq!(patch.endpoint, None);
+    }
+
+    #[test]
+    fn test_build_patch_blanks_a_field_named_in_clear() {
+        let mut params = update_params("cf-api");
+        params.clear = Some(vec!["endpoint".to_string()]);
+        let patch = build_patch(params).expect("a clear is a patch");
+        assert_eq!(patch.endpoint, Some(None));
+        assert_eq!(patch.env, None);
+    }
+
+    #[test]
+    fn test_build_patch_refuses_a_field_that_is_both_set_and_cleared() {
+        let mut params = update_params("cf-api");
+        params.purpose = Some("deploys the worker".to_string());
+        params.clear = Some(vec!["purpose".to_string()]);
+        let err = build_patch(params).unwrap_err();
+        assert_eq!(
+            err,
+            "`purpose` is both set and listed in `clear`; pass one or the other"
+        );
+    }
+
+    #[test]
+    fn test_build_patch_refuses_a_call_that_changes_nothing() {
+        let err = build_patch(update_params("cf-api")).unwrap_err();
+        assert!(err.starts_with("nothing to change"), "{err}");
+    }
+
+    #[test]
+    fn test_build_patch_surfaces_an_unreadable_expiry() {
+        let mut params = update_params("cf-api");
+        params.expires_at = Some("whenever".to_string());
+        let err = build_patch(params).unwrap_err();
+        assert!(err.contains("RFC 3339"), "{err}");
+    }
+
+    #[test]
+    fn test_build_patch_reads_both_expiry_shapes() {
+        let mut params = update_params("cf-api");
+        params.expires_at = Some("2027-01-01".to_string());
+        let patch = build_patch(params).expect("a date is an expiry");
+        assert_eq!(
+            patch.expires_at,
+            Some(Some(parse_expiry("2027-01-01").unwrap()))
+        );
+    }
 }