refactor: rename hint_set → role across MCP, REST, and OpenAPI

Every UAT session flagged hint_set as confusing — "hints" is protocol
jargon. The REPL and CLI already use "role" (role entry, role prefer
exit, role auto). This aligns MCP and REST to match:

- MCP: hint_set → role, hint_set_auto → role_auto
- REST: PUT/DELETE /hints → PUT/DELETE /role
- OpenAPI: HintSetRequest → RoleSetRequest, operationIds updated
- level parameter now defaults to "fixed" (matches REPL: "role entry"
  means "role fixed entry")

Also: removed confusing connect=false/listen=false from info output
capabilities — the address fields already show this information.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: maxholman

AGENTS.md

@@ -61,9 +61,13 @@ add, remove, or change any route, request body, or response shape in
   (source, destination, target) and concrete entities (peer, tun, device).
 - Explicit identifiers: Code and logs must use explicit, fixed IDs (e.g., peer1,
   dmz1, nodeA). Do not use network roles as variable names.
-- CLI consistency: eg REPL route add examples must explicitly include the --name
-  <peer> flag on exit/relay commands to ensure routing examples remain
-  self-documenting.
+- **Interface parity (STRICT):** All interfaces — REPL, CLI, MCP, REST API, and
+  OpenAPI spec — must expose identical operations with identical names,
+  parameters, and defaults. The REPL is the reference implementation. When
+  adding or changing any command, update ALL interfaces in the same commit.
+  Never create interface-specific names (e.g. `hint_set` in MCP when the REPL
+  uses `role`). Never split into separate tools what the REPL handles as one
+  command.
 
 ## TRIPLE PR Process for lead-agent only
 

crates/api/src/handlers.rs

@@ -125,13 +125,21 @@ pub struct ListenResponse {
     pub fingerprint: String,
 }
 
-/// Set hint request body.
+/// Role set request body.
+///
+/// `role` is always required. `level` defaults to `"fixed"` if omitted,
+/// matching the REPL behaviour where `role entry` means `role fixed entry`.
 #[derive(Debug, Deserialize)]
-pub struct HintSetRequestBody {
+pub struct RoleSetRequestBody {
+    #[serde(default = "default_level")]
     pub level: String,
     pub role: String,
 }
 
+fn default_level() -> String {
+    "fixed".to_string()
+}
+
 /// Logs query parameters.
 #[derive(Debug, Deserialize)]
 pub struct LogsQuery {
@@ -655,10 +663,14 @@ pub async fn shutdown(State(state): State<ApiState>) -> (StatusCode, Json<Succes
     }
 }
 
-pub async fn hint_set(
+pub async fn role_set(
     State(state): State<ApiState>,
-    Json(req): Json<HintSetRequestBody>,
+    Json(req): Json<RoleSetRequestBody>,
 ) -> (StatusCode, Json<SuccessResponse>) {
+    if req.role == "auto" {
+        return role_auto(State(state)).await;
+    }
+
     let level = match req.level.as_str() {
         "prefer" => HintLevel::Prefer,
         "exclude" => HintLevel::Exclude,
@@ -669,7 +681,7 @@ pub async fn hint_set(
                 Json(SuccessResponse {
                     success: false,
                     message: Some(format!(
-                        "invalid hint level '{}' (expected: prefer, exclude, fixed)",
+                        "invalid level '{}' (expected: prefer, exclude, fixed)",
                         req.level
                     )),
                 }),
@@ -686,7 +698,7 @@ pub async fn hint_set(
                 Json(SuccessResponse {
                     success: false,
                     message: Some(format!(
-                        "invalid role '{}' (expected: entry, exit, relay)",
+                        "invalid role '{}' (expected: auto, entry, exit, relay)",
                         req.role
                     )),
                 }),
@@ -738,7 +750,7 @@ pub async fn hint_set(
     }
 }
 
-pub async fn hint_set_auto(State(state): State<ApiState>) -> (StatusCode, Json<SuccessResponse>) {
+pub async fn role_auto(State(state): State<ApiState>) -> (StatusCode, Json<SuccessResponse>) {
     let resp = state
         .ipc
         .lock()

crates/api/src/lib.rs

@@ -77,10 +77,7 @@ pub fn router(state: State) -> Router {
         .route("/listen", post(handlers::listen))
         .route("/disconnect", post(handlers::disconnect))
         .route("/shutdown", post(handlers::shutdown))
-        .route(
-            "/hints",
-            put(handlers::hint_set).delete(handlers::hint_set_auto),
-        )
+        .route("/role", put(handlers::role_set))
         .layer(middleware::from_fn(move |req, next| {
             let auth = auth.clone();
             auth::middleware(auth, req, next)

crates/cli/src/output.rs

@@ -115,10 +115,7 @@ pub fn print_response(resp: &ManagementResponse) -> Result<(), CtlError> {
             if !s.listen_addr.is_empty() {
                 println!("{:<18} {}", "listen addr:", s.listen_addr);
             }
-            println!(
-                "{:<18} tun={} listen={} connect={}",
-                "capabilities:", s.tun_capable, s.listening, s.connecting
-            );
+            println!("{:<18} {}", "tun:", s.tun_capable);
             println!("{:<18} {}", "version:", s.version);
             println!("{:<18} {}", "uptime:", uptime);
         }

crates/daemon/src/lib.rs

@@ -140,9 +140,7 @@ pub fn start_node(
         ModeConfig::Auto(cfg) => match &cfg.hint {
             Some(hint) if hint.level == wallhack_wire::data::HintLevel::Fixed as i32 => {
                 wallhack_wire::data::NodeRole::try_from(hint.target)
-                    .ok()
-                    .map(NodeRole::from)
-                    .unwrap_or(NodeRole::Indeterminate)
+                    .map_or(NodeRole::Indeterminate, NodeRole::from)
             }
             _ => NodeRole::Indeterminate,
         },

crates/mcp/src/convert.rs

@@ -18,11 +18,7 @@ pub fn format_response(resp: &ManagementResponse) -> Result<String, String> {
             if !s.listen_addr.is_empty() {
                 let _ = writeln!(out, "listen addr: {}", s.listen_addr);
             }
-            let _ = writeln!(
-                out,
-                "capabilities: tun={} listen={} connect={}",
-                s.tun_capable, s.listening, s.connecting,
-            );
+            let _ = writeln!(out, "tun: {}", s.tun_capable);
             let _ = writeln!(out, "version: {}", s.version);
             let _ = writeln!(out, "uptime: {}", format_uptime(s.uptime_ms));
             Ok(out)

crates/mcp/src/tools.rs

@@ -43,11 +43,16 @@ pub struct LogsParams {
 }
 
 #[derive(Debug, serde::Deserialize, schemars::JsonSchema)]
-pub struct HintSetParams {
-    /// How strongly to apply the hint: "prefer" (soft), "exclude" (avoid), or "fixed" (force)
-    pub level: String,
-    /// Target role: "entry", "exit", or "relay"
+pub struct RoleParams {
+    /// "auto" to clear, or a role: "entry", "exit", "relay"
     pub role: String,
+    /// How to apply (ignored when role is "auto"): "fixed" (default), "prefer", or "exclude"
+    #[serde(default = "default_role_level")]
+    pub level: String,
+}
+
+fn default_role_level() -> String {
+    "fixed".to_string()
 }
 
 /// Wallhack MCP server — exposes daemon management as MCP tools.
@@ -182,19 +187,25 @@ impl WallhackServer {
     }
 
     #[tool(
-        description = "Set a role hint to influence auto-negotiation: \"prefer\" makes the role more likely, \"exclude\" prevents it, \"fixed\" forces it"
+        description = "Set or clear this node's role. Examples: role entry (force entry), role prefer exit (soft preference), role exclude relay (avoid relay), role auto (clear all, return to negotiation)"
     )]
-    async fn hint_set(
+    async fn role(
         &self,
-        Parameters(params): Parameters<HintSetParams>,
+        Parameters(params): Parameters<RoleParams>,
     ) -> Result<String, rmcp::ErrorData> {
+        if params.role == "auto" {
+            return ipc_call(management_request::Request::HintSetAuto(
+                HintSetAutoRequest {},
+            ))
+            .await;
+        }
         let level = match params.level.as_str() {
             "prefer" => HintLevel::Prefer,
             "exclude" => HintLevel::Exclude,
             "fixed" => HintLevel::Fixed,
             other => {
                 return Err(rmcp::ErrorData::invalid_params(
-                    format!("invalid hint level '{other}' (expected: prefer, exclude, fixed)"),
+                    format!("invalid level '{other}' (expected: prefer, exclude, fixed)"),
                     None,
                 ));
             }
@@ -205,7 +216,7 @@ impl WallhackServer {
             "relay" => NodeRole::Relay,
             other => {
                 return Err(rmcp::ErrorData::invalid_params(
-                    format!("invalid role '{other}' (expected: entry, exit, relay)"),
+                    format!("invalid role '{other}' (expected: auto, entry, exit, relay)"),
                     None,
                 ));
             }
@@ -216,16 +227,6 @@ impl WallhackServer {
         }))
         .await
     }
-
-    #[tool(
-        description = "Remove all role hints and return to automatic role negotiation based on peer capabilities. Use to undo a previous hint_set."
-    )]
-    async fn hint_set_auto(&self) -> Result<String, rmcp::ErrorData> {
-        ipc_call(management_request::Request::HintSetAuto(
-            HintSetAutoRequest {},
-        ))
-        .await
-    }
 }
 
 impl rmcp::ServerHandler for WallhackServer {

website/src/data/openapi.json

@@ -282,19 +282,20 @@
 					}
 				}
 			},
-			"HintSetRequest": {
+			"RoleSetRequest": {
 				"type": "object",
-				"required": ["level", "role"],
+				"required": ["role"],
 				"properties": {
-					"level": {
+					"role": {
 						"type": "string",
-						"enum": ["prefer", "exclude", "fixed"],
-						"description": "Hint strength: prefer (soft), exclude (medium), fixed (hard)."
+						"enum": ["auto", "entry", "exit", "relay"],
+						"description": "Target role, or \"auto\" to clear all preferences."
 					},
-					"role": {
+					"level": {
 						"type": "string",
-						"enum": ["entry", "exit", "relay"],
-						"description": "Role to apply the hint to."
+						"enum": ["prefer", "exclude", "fixed"],
+						"default": "fixed",
+						"description": "How to apply: fixed (default, force), prefer (soft), exclude (avoid)."
 					}
 				}
 			}
@@ -623,47 +624,30 @@
 				}
 			}
 		},
-		"/hints": {
+		"/role": {
 			"put": {
-				"summary": "Set role hint",
-				"description": "Configures a negotiation hint to influence auto-role resolution.",
-				"operationId": "hintSet",
+				"summary": "Set role",
+				"description": "Set or clear this node's role. Use role=auto to clear all preferences and return to negotiation.",
+				"operationId": "roleSet",
 				"security": [{ "basicAuth": [] }],
 				"requestBody": {
 					"required": true,
 					"content": {
 						"application/json": {
-							"schema": { "$ref": "#/components/schemas/HintSetRequest" }
+							"schema": { "$ref": "#/components/schemas/RoleSetRequest" }
 						}
 					}
 				},
 				"responses": {
 					"200": {
-						"description": "Hint applied.",
-						"content": {
-							"application/json": {
-								"schema": { "$ref": "#/components/schemas/SuccessResponse" }
-							}
-						}
-					},
-					"400": { "description": "Invalid hint level or role." },
-					"401": { "description": "Unauthorized." }
-				}
-			},
-			"delete": {
-				"summary": "Auto-negotiate",
-				"description": "Returns to pure capability-based negotiation by removing all role hints.",
-				"operationId": "hintSetAuto",
-				"security": [{ "basicAuth": [] }],
-				"responses": {
-					"200": {
-						"description": "Hints cleared.",
+						"description": "Role applied.",
 						"content": {
 							"application/json": {
 								"schema": { "$ref": "#/components/schemas/SuccessResponse" }
 							}
 						}
 					},
+					"400": { "description": "Invalid level or role." },
 					"401": { "description": "Unauthorized." }
 				}
 			}