@@ -559,6 +559,13 @@ export function buildLastActionResult(
559559 const code = getStringField(payload, "code") ?? "unknown";
560560 const message = getStringField(payload, "message") ?? "Unknown error";
561561 lines.push(`- ERROR [${code}]: ${message}`);
562+
563+ // Add recovery guidance for known error codes
564+ const guidance = getErrorRecoveryGuidance(code);
565+ if (guidance) {
566+ lines.push(` -> SOLUTION: ${guidance}`);
567+ }
568+
562569 appended = true;
563570 continue;
564571 }
@@ -1269,3 +1276,33 @@ function truncateText(value: string, max: number): string {
12691276 if (max <= 3) return value.slice(0, max);
12701277 return `${value.slice(0, max - 3)}...`;
12711278 }
1279+
1280+function getErrorRecoveryGuidance(errorCode: string): string | null {
1281+ const guidanceMap: Record<string, string> = {
1282+ docked:
1283+ 'Use action "undock" with args {} to leave the station, then retry your action',
1284+ not_docked:
1285+ 'Use action "dock" with args {} to dock at the current POI\'s base, then retry your action',
1286+ no_fuel:
1287+ 'Use action "refuel" at a base to restore fuel (requires docking first if not already docked)',
1288+ no_credits:
1289+ "Insufficient credits. Mine resources or sell items to earn credits",
1290+ no_cargo_space: "Cargo hold full. Sell items at a base to free up space",
1291+ invalid_target:
1292+ 'Target not found. Use "nearby" action to refresh target list',
1293+ invalid_poi:
1294+ 'Unknown POI ID. Use "system" action to see valid POI IDs in current system',
1295+ wrong_system:
1296+ 'Target POI is in a different system. Use "jump" to travel there first',
1297+ not_connected:
1298+ 'Systems not connected. Use "system" to check connections and find a route',
1299+ already_traveling:
1300+ "Already in transit. Wait for arrival before issuing new travel commands",
1301+ already_jumping:
1302+ "Already jumping. Wait for arrival before issuing new jump commands",
1303+ rate_limited:
1304+ "Too many actions this tick. Wait for next tick (~10 seconds)",
1305+ };
1306+
1307+ return guidanceMap[errorCode] ?? null;
1308+}