feat(session): Add namespaced session defaults profiles

Add profile-aware session defaults so agents can switch between global and named defaults in multi-target projects. Keep existing global defaults behavior fully backward compatible while enabling per-profile persistence in project config.

Add session_use_defaults_profile, config schema support, runtime/bootstrap wiring, docs updates, and tests for profile activation and persistence behavior.

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

Author: cameroncooke

docs/SESSION_DEFAULTS.md

@@ -25,6 +25,40 @@ The persistence is patch-only: only keys provided in that call are written (plus
 
 You can also manually create the config file to essentially seed the defaults at startup; see [CONFIGURATION.md](CONFIGURATION.md) for more information.
 
+## Namespaced profiles
+Session defaults support named profiles so one workspace can keep separate defaults for iOS/watchOS/macOS (or any custom profile names).
+
+- Use `session_use_defaults_profile` to switch the active profile.
+- Existing tools (`session_set_defaults`, `session_show_defaults`, build/test tools) use the active profile automatically.
+- Use `global: true` to switch back to the unnamed global profile.
+- Set `persist: true` on `session_use_defaults_profile` to write `activeSessionDefaultsProfile` in `.xcodebuildmcp/config.yaml`.
+
+## Recommended startup flow (monorepo / multi-target)
+Copy/paste this sequence when starting a new session:
+
+```json
+{"name":"session_use_defaults_profile","arguments":{"profile":"ios","persist":true}}
+{"name":"session_set_defaults","arguments":{
+  "workspacePath":"/repo/MyApp.xcworkspace",
+  "scheme":"MyApp-iOS",
+  "simulatorName":"iPhone 16 Pro",
+  "persist":true
+}}
+{"name":"session_show_defaults","arguments":{}}
+```
+
+Switch targets later in the same session:
+
+```json
+{"name":"session_use_defaults_profile","arguments":{"profile":"watch","persist":true}}
+{"name":"session_set_defaults","arguments":{
+  "workspacePath":"/repo/MyApp.xcworkspace",
+  "scheme":"MyApp-watchOS",
+  "simulatorName":"Apple Watch Series 10 (45mm)",
+  "persist":true
+}}
+```
+
 ## Related docs
 - Configuration options: [CONFIGURATION.md](CONFIGURATION.md)
 - Tools reference: [TOOLS.md](TOOLS.md)

docs/TOOLS-CLI.md

@@ -189,4 +189,4 @@ XcodeBuildMCP provides 73 canonical tools organized into 13 workflow groups.
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T14:53:05.834Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T16:38:52.535Z UTC*

docs/TOOLS.md

@@ -1,6 +1,6 @@
 # XcodeBuildMCP MCP Tools Reference
 
-This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP provides 78 canonical tools organized into 15 workflow groups for comprehensive Apple development workflows.
+This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP provides 79 canonical tools organized into 15 workflow groups for comprehensive Apple development workflows.
 
 ## Workflow Groups
 
@@ -126,11 +126,12 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 
 ### Session Management (`session-management`)
-**Purpose**: Manage session defaults for project/workspace paths, scheme, configuration, simulator/device settings. (4 tools)
+**Purpose**: Manage session defaults for project/workspace paths, scheme, configuration, simulator/device settings. (5 tools)
 
 - `session_clear_defaults` - Clear session defaults.
 - `session_set_defaults` - Set the session defaults, should be called at least once to set tool defaults.
 - `session_show_defaults` - Show session defaults.
+- `session_use_defaults_profile` - Select the active session defaults profile for multi-target workflows.
 - `sync_xcode_defaults` - Sync session defaults (scheme, simulator) from Xcode's current IDE selection.
 
 
@@ -198,10 +199,10 @@ This document lists MCP tool names as exposed to MCP clients. XcodeBuildMCP prov
 
 ## Summary Statistics
 
-- **Canonical Tools**: 78
-- **Total Tools**: 102
+- **Canonical Tools**: 79
+- **Total Tools**: 103
 - **Workflow Groups**: 15
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T14:53:05.834Z UTC*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` from the tools manifest. Last updated: 2026-02-17T16:38:52.535Z UTC*

manifests/tools/session_use_defaults_profile.yaml

@@ -0,0 +1,9 @@
+id: session_use_defaults_profile
+module: mcp/tools/session-management/session_use_defaults_profile
+names:
+  mcp: session_use_defaults_profile
+  cli: use-defaults-profile
+description: Select the active session defaults profile for multi-target workflows.
+annotations:
+  title: Use Session Defaults Profile
+  readOnlyHint: true

manifests/workflows/session-management.yaml

@@ -9,6 +9,7 @@ selection:
     autoInclude: true
 tools:
   - session_show_defaults
+  - session_use_defaults_profile
   - session_set_defaults
   - session_clear_defaults
   - sync_xcode_defaults

src/cli/yargs-app.ts

@@ -57,7 +57,7 @@ export function buildYargsApp(opts: YargsAppOptions): ReturnType<typeof yargs> {
         setLogLevel(level);
       }
     })
-    .version(version)
+    .version(String(version))
     .help()
     .alias('h', 'help')
     .alias('v', 'version')

src/core/manifest/__tests__/load-manifest.test.ts

@@ -33,6 +33,7 @@ describe('load-manifest', () => {
       expect(manifest.tools.has('build_sim')).toBe(true);
       expect(manifest.tools.has('discover_projs')).toBe(true);
       expect(manifest.tools.has('session_show_defaults')).toBe(true);
+      expect(manifest.tools.has('session_use_defaults_profile')).toBe(true);
     });
 
     it('should validate tool references in workflows', () => {

src/daemon.ts

@@ -392,7 +392,7 @@ async function main(): Promise<void> {
       pid: process.pid,
       startedAt,
       enabledWorkflows: daemonWorkflows,
-      version,
+      version: String(version),
     });
 
     writeLine(`Daemon started (PID: ${process.pid})`);

src/mcp/tools/doctor/doctor.ts

@@ -136,7 +136,7 @@ export async function runDoctor(
   );
 
   const doctorInfo = {
-    serverVersion: version,
+    serverVersion: String(version),
     timestamp: new Date().toISOString(),
     system: systemInfo,
     node: nodeInfo,

src/mcp/tools/session-management/__tests__/session_clear_defaults.test.ts

@@ -50,12 +50,17 @@ describe('session-clear-defaults tool', () => {
     });
 
     it('should clear all when all=true', async () => {
+      sessionStore.setActiveProfile('ios');
+      sessionStore.setDefaults({ scheme: 'IOS' });
+      sessionStore.setActiveProfile(null);
       const result = await sessionClearDefaultsLogic({ all: true });
       expect(result.isError).toBe(false);
       expect(result.content[0].text).toBe('Session defaults cleared');
 
       const current = sessionStore.getAll();
       expect(Object.keys(current).length).toBe(0);
+      expect(sessionStore.listProfiles()).toEqual([]);
+      expect(sessionStore.getActiveProfile()).toBeNull();
     });
 
     it('should clear all when no params provided', async () => {