Add port mappings feature, update app icon, and enhance default instructions

- Add per-project port mapping configuration (host:container port pairs with
  TCP/UDP protocol) stored in project config and applied as Docker port
  bindings at container creation. Port changes trigger automatic container
  recreation via fingerprint detection.
- Create PortMappingsModal UI component following the same pattern as
  EnvVarsModal, integrated into ProjectCard config panel.
- Inject port mapping details into CLAUDE_INSTRUCTIONS so Claude inside the
  container knows which ports are available for testing services.
- Update default global instructions for new installs to encourage use of
  subagents for long-running and parallel tasks.
- Replace app icons with new v2 sun logo design for better visibility at
  small sizes (taskbar/dock).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

app/src-tauri/src/docker/container.rs

@@ -2,13 +2,13 @@ use bollard::container::{
     Config, CreateContainerOptions, ListContainersOptions, RemoveContainerOptions,
     StartContainerOptions, StopContainerOptions,
 };
-use bollard::models::{ContainerSummary, HostConfig, Mount, MountTypeEnum};
+use bollard::models::{ContainerSummary, HostConfig, Mount, MountTypeEnum, PortBinding};
 use std::collections::HashMap;
 use std::collections::hash_map::DefaultHasher;
 use std::hash::{Hash, Hasher};
 
 use super::client::get_docker;
-use crate::models::{AuthMode, BedrockAuthMethod, ContainerInfo, EnvVar, GlobalAwsSettings, Project, ProjectPath};
+use crate::models::{AuthMode, BedrockAuthMethod, ContainerInfo, EnvVar, GlobalAwsSettings, PortMapping, Project, ProjectPath};
 
 /// Compute a fingerprint string for the custom environment variables.
 /// Sorted alphabetically so order changes do not cause spurious recreation.
@@ -95,6 +95,20 @@ fn compute_paths_fingerprint(paths: &[ProjectPath]) -> String {
     format!("{:x}", hasher.finish())
 }
 
+/// Compute a fingerprint for port mappings so we can detect changes.
+/// Sorted so order changes don't cause spurious recreation.
+fn compute_ports_fingerprint(port_mappings: &[PortMapping]) -> String {
+    let mut parts: Vec<String> = port_mappings
+        .iter()
+        .map(|p| format!("{}:{}:{}", p.host_port, p.container_port, p.protocol))
+        .collect();
+    parts.sort();
+    let joined = parts.join(",");
+    let mut hasher = DefaultHasher::new();
+    joined.hash(&mut hasher);
+    format!("{:x}", hasher.finish())
+}
+
 pub async fn find_existing_container(project: &Project) -> Result<Option<String>, String> {
     let docker = get_docker()?;
     let container_name = project.container_name();
@@ -255,11 +269,27 @@ pub async fn create_container(
     let custom_env_fingerprint = compute_env_fingerprint(&merged_env);
     env_vars.push(format!("TRIPLE_C_CUSTOM_ENV={}", custom_env_fingerprint));
 
-    // Claude instructions (global + per-project)
-    let combined_instructions = merge_claude_instructions(
+    // Claude instructions (global + per-project, plus port mapping info)
+    let mut combined_instructions = merge_claude_instructions(
         global_claude_instructions,
         project.claude_instructions.as_deref(),
     );
+    if !project.port_mappings.is_empty() {
+        let mut port_lines: Vec<String> = Vec::new();
+        port_lines.push("## Available Port Mappings".to_string());
+        port_lines.push("The following ports are mapped from the host to this container. Use these container ports when starting services that need to be accessible from the host:".to_string());
+        for pm in &project.port_mappings {
+            port_lines.push(format!(
+                "- Host port {} -> Container port {} ({})",
+                pm.host_port, pm.container_port, pm.protocol
+            ));
+        }
+        let port_info = port_lines.join("\n");
+        combined_instructions = Some(match combined_instructions {
+            Some(existing) => format!("{}\n\n{}", existing, port_info),
+            None => port_info,
+        });
+    }
     if let Some(ref instructions) = combined_instructions {
         env_vars.push(format!("CLAUDE_INSTRUCTIONS={}", instructions));
     }
@@ -346,6 +376,21 @@ pub async fn create_container(
         });
     }
 
+    // Port mappings
+    let mut exposed_ports: HashMap<String, HashMap<(), ()>> = HashMap::new();
+    let mut port_bindings: HashMap<String, Option<Vec<PortBinding>>> = HashMap::new();
+    for pm in &project.port_mappings {
+        let container_key = format!("{}/{}", pm.container_port, pm.protocol);
+        exposed_ports.insert(container_key.clone(), HashMap::new());
+        port_bindings.insert(
+            container_key,
+            Some(vec![PortBinding {
+                host_ip: Some("0.0.0.0".to_string()),
+                host_port: Some(pm.host_port.to_string()),
+            }]),
+        );
+    }
+
     let mut labels = HashMap::new();
     labels.insert("triple-c.managed".to_string(), "true".to_string());
     labels.insert("triple-c.project-id".to_string(), project.id.clone());
@@ -353,10 +398,12 @@ pub async fn create_container(
     labels.insert("triple-c.auth-mode".to_string(), format!("{:?}", project.auth_mode));
     labels.insert("triple-c.paths-fingerprint".to_string(), compute_paths_fingerprint(&project.paths));
     labels.insert("triple-c.bedrock-fingerprint".to_string(), compute_bedrock_fingerprint(project));
+    labels.insert("triple-c.ports-fingerprint".to_string(), compute_ports_fingerprint(&project.port_mappings));
     labels.insert("triple-c.image".to_string(), image_name.to_string());
 
     let host_config = HostConfig {
         mounts: Some(mounts),
+        port_bindings: if port_bindings.is_empty() { None } else { Some(port_bindings) },
         ..Default::default()
     };
 
@@ -373,6 +420,7 @@ pub async fn create_container(
         labels: Some(labels),
         working_dir: Some(working_dir),
         host_config: Some(host_config),
+        exposed_ports: if exposed_ports.is_empty() { None } else { Some(exposed_ports) },
         tty: Some(true),
         ..Default::default()
     };
@@ -488,6 +536,14 @@ pub async fn container_needs_recreation(
         }
     }
 
+    // ── Port mappings fingerprint ──────────────────────────────────────────
+    let expected_ports_fp = compute_ports_fingerprint(&project.port_mappings);
+    let container_ports_fp = get_label("triple-c.ports-fingerprint").unwrap_or_default();
+    if container_ports_fp != expected_ports_fp {
+        log::info!("Port mappings fingerprint mismatch (container={:?}, expected={:?})", container_ports_fp, expected_ports_fp);
+        return Ok(true);
+    }
+
     // ── Bedrock config fingerprint ───────────────────────────────────────
     let expected_bedrock_fp = compute_bedrock_fingerprint(project);
     let container_bedrock_fp = get_label("triple-c.bedrock-fingerprint").unwrap_or_default();

app/src-tauri/src/models/app_settings.rs

@@ -7,7 +7,7 @@ fn default_true() -> bool {
 }
 
 fn default_global_instructions() -> Option<String> {
-    Some("If the project is not initialized with git, recommend to the user to initialize and use git to track changes. This makes it easier to revert should something break.".to_string())
+    Some("If the project is not initialized with git, recommend to the user to initialize and use git to track changes. This makes it easier to revert should something break.\n\nUse subagents frequently. For long-running tasks, break the work into parallel subagents where possible. When handling multiple separate tasks, delegate each to its own subagent so they can run concurrently.".to_string())
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]

app/src-tauri/src/models/project.rs

@@ -12,6 +12,18 @@ pub struct ProjectPath {
     pub mount_name: String,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
+pub struct PortMapping {
+    pub host_port: u16,
+    pub container_port: u16,
+    #[serde(default = "default_protocol")]
+    pub protocol: String,
+}
+
+fn default_protocol() -> String {
+    "tcp".to_string()
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Project {
     pub id: String,
@@ -30,6 +42,8 @@ pub struct Project {
     #[serde(default)]
     pub custom_env_vars: Vec<EnvVar>,
     #[serde(default)]
+    pub port_mappings: Vec<PortMapping>,
+    #[serde(default)]
     pub claude_instructions: Option<String>,
     pub created_at: String,
     pub updated_at: String,
@@ -114,6 +128,7 @@ impl Project {
             git_user_name: None,
             git_user_email: None,
             custom_env_vars: Vec::new(),
+            port_mappings: Vec::new(),
             claude_instructions: None,
             created_at: now.clone(),
             updated_at: now,

app/src/components/projects/PortMappingsModal.tsx

@@ -0,0 +1,157 @@
+import { useState, useEffect, useRef, useCallback } from "react";
+import type { PortMapping } from "../../lib/types";
+
+interface Props {
+  portMappings: PortMapping[];
+  disabled: boolean;
+  onSave: (mappings: PortMapping[]) => Promise<void>;
+  onClose: () => void;
+}
+
+export default function PortMappingsModal({ portMappings: initial, disabled, onSave, onClose }: Props) {
+  const [mappings, setMappings] = useState<PortMapping[]>(initial);
+  const overlayRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [onClose]);
+
+  const handleOverlayClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (e.target === overlayRef.current) onClose();
+    },
+    [onClose],
+  );
+
+  const updatePort = (index: number, field: "host_port" | "container_port", value: string) => {
+    const updated = [...mappings];
+    const num = parseInt(value, 10);
+    updated[index] = { ...updated[index], [field]: isNaN(num) ? 0 : num };
+    setMappings(updated);
+  };
+
+  const updateProtocol = (index: number, value: string) => {
+    const updated = [...mappings];
+    updated[index] = { ...updated[index], protocol: value };
+    setMappings(updated);
+  };
+
+  const removeMapping = async (index: number) => {
+    const updated = mappings.filter((_, i) => i !== index);
+    setMappings(updated);
+    try { await onSave(updated); } catch (err) {
+      console.error("Failed to remove port mapping:", err);
+    }
+  };
+
+  const addMapping = async () => {
+    const updated = [...mappings, { host_port: 0, container_port: 0, protocol: "tcp" }];
+    setMappings(updated);
+    try { await onSave(updated); } catch (err) {
+      console.error("Failed to add port mapping:", err);
+    }
+  };
+
+  const handleBlur = async () => {
+    try { await onSave(mappings); } catch (err) {
+      console.error("Failed to update port mappings:", err);
+    }
+  };
+
+  return (
+    <div
+      ref={overlayRef}
+      onClick={handleOverlayClick}
+      className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
+    >
+      <div className="bg-[var(--bg-secondary)] border border-[var(--border-color)] rounded-lg p-6 w-[36rem] shadow-xl max-h-[80vh] overflow-y-auto">
+        <h2 className="text-lg font-semibold mb-2">Port Mappings</h2>
+        <p className="text-xs text-[var(--text-secondary)] mb-4">
+          Map host ports to container ports. Services can be started after the container is running.
+        </p>
+
+        {disabled && (
+          <div className="px-2 py-1.5 mb-3 bg-[var(--warning)]/15 border border-[var(--warning)]/30 rounded text-xs text-[var(--warning)]">
+            Container must be stopped to change port mappings.
+          </div>
+        )}
+
+        <div className="space-y-2 mb-4">
+          {mappings.length === 0 && (
+            <p className="text-xs text-[var(--text-secondary)]">No port mappings configured.</p>
+          )}
+          {mappings.length > 0 && (
+            <div className="flex gap-2 items-center text-xs text-[var(--text-secondary)] px-0.5">
+              <span className="w-[30%]">Host Port</span>
+              <span className="w-[30%]">Container Port</span>
+              <span className="w-[25%]">Protocol</span>
+              <span className="w-[15%]" />
+            </div>
+          )}
+          {mappings.map((pm, i) => (
+            <div key={i} className="flex gap-2 items-center">
+              <input
+                type="number"
+                min="1"
+                max="65535"
+                value={pm.host_port || ""}
+                onChange={(e) => updatePort(i, "host_port", e.target.value)}
+                onBlur={handleBlur}
+                placeholder="8080"
+                disabled={disabled}
+                className="w-[30%] px-2 py-1.5 bg-[var(--bg-primary)] border border-[var(--border-color)] rounded text-sm text-[var(--text-primary)] focus:outline-none focus:border-[var(--accent)] disabled:opacity-50 font-mono"
+              />
+              <input
+                type="number"
+                min="1"
+                max="65535"
+                value={pm.container_port || ""}
+                onChange={(e) => updatePort(i, "container_port", e.target.value)}
+                onBlur={handleBlur}
+                placeholder="8080"
+                disabled={disabled}
+                className="w-[30%] px-2 py-1.5 bg-[var(--bg-primary)] border border-[var(--border-color)] rounded text-sm text-[var(--text-primary)] focus:outline-none focus:border-[var(--accent)] disabled:opacity-50 font-mono"
+              />
+              <select
+                value={pm.protocol}
+                onChange={(e) => { updateProtocol(i, e.target.value); handleBlur(); }}
+                disabled={disabled}
+                className="w-[25%] px-2 py-1.5 bg-[var(--bg-primary)] border border-[var(--border-color)] rounded text-sm text-[var(--text-primary)] focus:outline-none focus:border-[var(--accent)] disabled:opacity-50"
+              >
+                <option value="tcp">TCP</option>
+                <option value="udp">UDP</option>
+              </select>
+              <button
+                onClick={() => removeMapping(i)}
+                disabled={disabled}
+                className="w-[15%] px-2 py-1.5 text-sm text-[var(--error)] hover:bg-[var(--bg-primary)] rounded disabled:opacity-50 transition-colors text-center"
+              >
+                x
+              </button>
+            </div>
+          ))}
+        </div>
+
+        <div className="flex justify-between items-center">
+          <button
+            onClick={addMapping}
+            disabled={disabled}
+            className="text-sm text-[var(--accent)] hover:text-[var(--accent-hover)] disabled:opacity-50 transition-colors"
+          >
+            + Add port mapping
+          </button>
+          <button
+            onClick={onClose}
+            className="px-4 py-2 text-sm text-[var(--text-secondary)] hover:text-[var(--text-primary)] transition-colors"
+          >
+            Close
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

app/src/components/projects/ProjectCard.tsx

@@ -5,6 +5,7 @@ import { useProjects } from "../../hooks/useProjects";
 import { useTerminal } from "../../hooks/useTerminal";
 import { useAppState } from "../../store/appState";
 import EnvVarsModal from "./EnvVarsModal";
+import PortMappingsModal from "./PortMappingsModal";
 import ClaudeInstructionsModal from "./ClaudeInstructionsModal";
 
 interface Props {
@@ -20,6 +21,7 @@ export default function ProjectCard({ project }: Props) {
   const [error, setError] = useState<string | null>(null);
   const [showConfig, setShowConfig] = useState(false);
   const [showEnvVarsModal, setShowEnvVarsModal] = useState(false);
+  const [showPortMappingsModal, setShowPortMappingsModal] = useState(false);
   const [showClaudeInstructionsModal, setShowClaudeInstructionsModal] = useState(false);
   const isSelected = selectedProjectId === project.id;
   const isStopped = project.status === "stopped" || project.status === "error";
@@ -32,6 +34,7 @@ export default function ProjectCard({ project }: Props) {
   const [gitToken, setGitToken] = useState(project.git_token ?? "");
   const [claudeInstructions, setClaudeInstructions] = useState(project.claude_instructions ?? "");
   const [envVars, setEnvVars] = useState(project.custom_env_vars ?? []);
+  const [portMappings, setPortMappings] = useState(project.port_mappings ?? []);
 
   // Bedrock local state for text fields
   const [bedrockRegion, setBedrockRegion] = useState(project.bedrock_config?.aws_region ?? "us-east-1");
@@ -51,6 +54,7 @@ export default function ProjectCard({ project }: Props) {
     setGitToken(project.git_token ?? "");
     setClaudeInstructions(project.claude_instructions ?? "");
     setEnvVars(project.custom_env_vars ?? []);
+    setPortMappings(project.port_mappings ?? []);
     setBedrockRegion(project.bedrock_config?.aws_region ?? "us-east-1");
     setBedrockAccessKeyId(project.bedrock_config?.aws_access_key_id ?? "");
     setBedrockSecretKey(project.bedrock_config?.aws_secret_access_key ?? "");
@@ -524,6 +528,19 @@ export default function ProjectCard({ project }: Props) {
                 </button>
               </div>
 
+              {/* Port Mappings */}
+              <div className="flex items-center justify-between">
+                <label className="text-xs text-[var(--text-secondary)]">
+                  Port Mappings{portMappings.length > 0 && ` (${portMappings.length})`}
+                </label>
+                <button
+                  onClick={() => setShowPortMappingsModal(true)}
+                  className="text-xs px-2 py-0.5 text-[var(--accent)] hover:text-[var(--accent-hover)] hover:bg-[var(--bg-primary)] rounded transition-colors"
+                >
+                  Edit
+                </button>
+              </div>
+
               {/* Claude Instructions */}
               <div className="flex items-center justify-between">
                 <label className="text-xs text-[var(--text-secondary)]">
@@ -682,6 +699,18 @@ export default function ProjectCard({ project }: Props) {
         />
       )}
 
+      {showPortMappingsModal && (
+        <PortMappingsModal
+          portMappings={portMappings}
+          disabled={!isStopped}
+          onSave={async (mappings) => {
+            setPortMappings(mappings);
+            await update({ ...project, port_mappings: mappings });
+          }}
+          onClose={() => setShowPortMappingsModal(false)}
+        />
+      )}
+
       {showClaudeInstructionsModal && (
         <ClaudeInstructionsModal
           instructions={claudeInstructions}

app/src/lib/types.ts

@@ -8,6 +8,12 @@ export interface ProjectPath {
   mount_name: string;
 }
 
+export interface PortMapping {
+  host_port: number;
+  container_port: number;
+  protocol: string;
+}
+
 export interface Project {
   id: string;
   name: string;
@@ -22,6 +28,7 @@ export interface Project {
   git_user_name: string | null;
   git_user_email: string | null;
   custom_env_vars: EnvVar[];
+  port_mappings: PortMapping[];
   claude_instructions: string | null;
   created_at: string;
   updated_at: string;