fix: layer Relay configuration by priority

crates/cli/README.md

@@ -152,8 +152,9 @@ nemo-relay run --agent codex --dry-run
 
 Project config lives at `./.nemo-relay/config.toml`; user config lives at
 `~/.config/nemo-relay/config.toml` or `$XDG_CONFIG_HOME/nemo-relay/config.toml`.
-The project layer overrides system config, and the user layer overrides the
-project layer.
+Runtime files layer from lowest to highest precedence as explicit-or-user,
+nearest project, then system. An explicit `--config` replaces the ambient user
+file without suppressing project or system configuration.
 
 Set up agent entries in the top-level config with:
 
@@ -186,8 +187,9 @@ nemo-relay plugins edit
 
 When the top-level CLI receives `--plugin-config-path`, the editor uses that
 exact file. Otherwise, `--config path/to/config.toml` makes the editor use the
-sibling `path/to/plugins.toml`, matching runtime selection. An explicit
-`--user`, `--project`, or `--global` editor flag overrides the inherited target.
+sibling `path/to/plugins.toml`, matching runtime selection. The explicit file
+replaces the user layer, so `--user` keeps that inherited target.
+`--project` and `--global` edit the other active layers.
 
 The top-level editor menu contains one entry per supported built-in, followed by
 the dynamic plugin references in the selected physical `plugins.toml`. Dynamic
@@ -202,6 +204,12 @@ The canonical plugin file is `plugins.toml`; user config lives at
 not store credentials there. The editor rejects schema-declared secret values
 in global plugin configuration.
 
+Runtime plugin files layer from lowest to highest precedence as
+explicit-or-user, nearest project, then system. An explicit
+`--plugin-config-path`, or a `plugins.toml` beside `--config`, replaces the
+ambient XDG user file without suppressing project or system policy. Missing
+files are skipped, and symlink aliases to one physical file are loaded once.
+
 Minimal ATIF example:
 
 ```toml

crates/cli/src/commands/configure/model.rs

@@ -42,9 +42,10 @@ pub(crate) fn plugins_edit_command_for_scope(
     scope: ConfigScope,
     explicit_path: Option<PathBuf>,
 ) -> PluginsEditRequest {
-    let scope = match scope {
-        ConfigScope::Project | ConfigScope::Both => ConfigurationScope::Project,
-        ConfigScope::Global => ConfigurationScope::User,
+    let scope = match (&explicit_path, scope) {
+        (Some(_), _) => ConfigurationScope::User,
+        (None, ConfigScope::Project | ConfigScope::Both) => ConfigurationScope::Project,
+        (None, ConfigScope::Global) => ConfigurationScope::User,
     };
     PluginsEditRequest {
         scope,

crates/cli/src/commands/plugins/subcommands.rs

@@ -72,7 +72,7 @@ impl PluginsSubcommand {
         .multiple(false)
 ))]
 pub(crate) struct PluginsScopeArgs {
-    /// Edit the user config at `$XDG_CONFIG_HOME/nemo-relay/plugins.toml`.
+    /// Edit the selected low layer: an explicit plugin target, or the XDG user config.
     #[arg(long)]
     pub(crate) user: bool,
     /// Edit the nearest project config at `.nemo-relay/plugins.toml`.
@@ -169,11 +169,12 @@ impl PluginsEditCommand {
         explicit_path: Option<PathBuf>,
     ) -> crate::plugins::PluginsEditRequest {
         let scope = self.scope.into();
-        let explicit_path = if matches!(scope, crate::plugins::ConfigurationScope::Default) {
-            explicit_path
-        } else {
-            None
-        };
+        let explicit_path = matches!(
+            scope,
+            crate::plugins::ConfigurationScope::Default | crate::plugins::ConfigurationScope::User
+        )
+        .then_some(explicit_path)
+        .flatten();
         crate::plugins::PluginsEditRequest {
             explicit_path,
             scope,

crates/cli/src/commands/serve.rs

@@ -8,7 +8,7 @@ use clap::Args;
 
 #[derive(Debug, Clone, Default, Args)]
 pub(crate) struct ServerArgs {
-    /// Path to an explicit config file (disables auto-discovery of workspace/global/system)
+    /// Path replacing the user config layer; project and system config still apply
     #[arg(long)]
     pub(super) config: Option<PathBuf>,
     /// Address for the gateway to listen on in daemon mode (default 127.0.0.1:4040)