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

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,9 +663,9 @@ 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>) {
     let level = match req.level.as_str() {
         "prefer" => HintLevel::Prefer,
@@ -738,7 +746,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).delete(handlers::role_auto))
         .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,
+pub struct RoleParams {
     /// Target role: "entry", "exit", or "relay"
     pub role: String,
+    /// How to apply: "fixed" (default, force this role), "prefer" (soft preference), or "exclude" (avoid this role)
+    #[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,19 @@ 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 this node's role: \"fixed\" forces a role (e.g. role fixed entry), \"prefer\" is a soft preference, \"exclude\" avoids a role. Use role_auto to clear."
     )]
-    async fn hint_set(
+    async fn role(
         &self,
-        Parameters(params): Parameters<HintSetParams>,
+        Parameters(params): Parameters<RoleParams>,
     ) -> Result<String, rmcp::ErrorData> {
         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,
                 ));
             }
@@ -218,9 +223,9 @@ impl WallhackServer {
     }
 
     #[tool(
-        description = "Remove all role hints and return to automatic role negotiation based on peer capabilities. Use to undo a previous hint_set."
+        description = "Clear all role preferences and return to automatic negotiation based on peer capabilities"
     )]
-    async fn hint_set_auto(&self) -> Result<String, rmcp::ErrorData> {
+    async fn role_auto(&self) -> Result<String, rmcp::ErrorData> {
         ipc_call(management_request::Request::HintSetAuto(
             HintSetAutoRequest {},
         ))

website/src/data/openapi.json

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