diff --git a/README.md b/README.md
index a8eb0ac54..37b491838 100644
--- a/README.md
+++ b/README.md
@@ -179,6 +179,11 @@ url     = "https://mcp.stripe.com"
 headers = { Authorization = "Bearer ${STRIPE_KEY}" }
 ```
 
+Enabled MCP servers start connecting automatically in the background after a
+session begins, so chat stays usable while tools come online. Use `/mcp` or the
+desktop MCP panel to refresh status, reconnect a server, inspect failures, or
+disable a server for the current session.
+
 **Already have an `.mcp.json`?** Drop it in the project root and Reasonix
 reads it as-is — the `mcpServers` spec (`command`/`args`/`env`, `type`/`url`/
 `headers`, `${VAR}` expansion) maps field-for-field onto `[[plugins]]`. Both
diff --git a/desktop/app.go b/desktop/app.go
index e89e5b1ab..68d1a770d 100644
--- a/desktop/app.go
+++ b/desktop/app.go
@@ -1467,14 +1467,17 @@ func skillRootsView() []SkillRootView {
 	cfg, _ := config.Load()
 	userCfg := config.LoadForEdit(config.UserConfigPath())
 	var custom []string
+	maxDepth := 3
 	if cfg != nil {
 		custom = cfg.SkillCustomPaths()
+		maxDepth = cfg.SkillMaxDepth()
 	}
-	st := skill.New(skill.Options{ProjectRoot: cwd, CustomPaths: custom, DisableBuiltins: true, Stderr: io.Discard})
+	st := skill.New(skill.Options{ProjectRoot: cwd, CustomPaths: custom, MaxDepth: maxDepth, DisableBuiltins: true, Stderr: io.Discard})
 	counts := map[string]int{}
 	skillItems := map[string][]SkillRootSkillView{}
+	roots := st.Roots()
 	for _, sk := range st.List() {
-		root := config.CanonicalSkillPath(filepath.Dir(skillRootPath(sk.Path)))
+		root := skillDisplayRoot(sk, roots)
 		counts[root]++
 		skillItems[root] = append(skillItems[root], SkillRootSkillView{
 			Name:        sk.Name,
@@ -1495,7 +1498,7 @@ func skillRootsView() []SkillRootView {
 		}
 	}
 	out := []SkillRootView{}
-	for _, r := range st.Roots() {
+	for _, r := range roots {
 		dir := config.CanonicalSkillPath(r.Dir)
 		view := SkillRootView{
 			Dir:        r.Dir,
@@ -1626,6 +1629,21 @@ func skillRootPath(path string) string {
 	return path
 }
 
+func skillDisplayRoot(sk skill.Skill, roots []skill.Root) string {
+	cleanPath := filepath.Clean(sk.Path)
+	for _, r := range roots {
+		if r.Scope != sk.Scope {
+			continue
+		}
+		cleanRoot := filepath.Clean(r.Dir)
+		prefix := cleanRoot + string(filepath.Separator)
+		if cleanPath == cleanRoot || strings.HasPrefix(cleanPath, prefix) {
+			return config.CanonicalSkillPath(r.Dir)
+		}
+	}
+	return config.CanonicalSkillPath(filepath.Dir(skillRootPath(sk.Path)))
+}
+
 // MCPServerInput is the drawer's "add server" form. Transport is "stdio" (Command
 // + Args + Env) or "http"/"sse" (URL). Mirrors config.PluginEntry's writable shape.
 type MCPServerInput struct {
@@ -1635,7 +1653,6 @@ type MCPServerInput struct {
 	Args      []string          `json:"args"`
 	URL       string            `json:"url"`
 	Env       map[string]string `json:"env"`
-	Tier      string            `json:"tier"`
 }
 
 // AddMCPServer connects a server live and persists it to config (Customize → MCP →
@@ -1652,8 +1669,8 @@ func (a *App) AddMCPServer(in MCPServerInput) (int, error) {
 		Args:    in.Args,
 		URL:     in.URL,
 		Env:     in.Env,
-		Tier:    normalizeMCPTier(in.Tier),
 	}
+	entry, _ = config.NormalizePluginCommandLine(entry)
 	if err := a.saveDesktopMCPServer(entry); err != nil {
 		return 0, err
 	}
@@ -1684,10 +1701,11 @@ func (a *App) UpdateMCPServer(name string, in MCPServerInput) error {
 	updated.Command = strings.TrimSpace(in.Command)
 	updated.Args = append([]string(nil), in.Args...)
 	updated.URL = strings.TrimSpace(in.URL)
-	updated.Tier = normalizeMCPTier(in.Tier)
+	updated.Tier = ""
 	if in.Env != nil {
 		updated.Env = in.Env
 	}
+	updated, _ = config.NormalizePluginCommandLine(updated)
 	if updated.Type == "stdio" {
 		updated.URL = ""
 	} else {
@@ -1743,15 +1761,26 @@ func (a *App) RemoveMCPServer(name string) error {
 	return fmt.Errorf("no MCP server named %q", name)
 }
 
-// RetryMCPServer reconnects a configured server that failed or was disconnected,
-// without touching config (the failed row's retry button).
-func (a *App) RetryMCPServer(name string) error {
+// ReconnectMCPServer disconnects the server if it is already connected (to force
+// a fresh handshake and tool re-registration), then reconnects.  Failures are
+// recorded on the Host so the UI can render them.
+func (a *App) ReconnectMCPServer(name string) error {
 	tab := a.activeTab()
 	if tab == nil || tab.Ctrl == nil {
 		return fmt.Errorf("no active session")
 	}
+	if mcpConnected(tab.Ctrl, name) {
+		tab.Ctrl.DisconnectMCPServer(name)
+	}
 	_, err := a.connectConfiguredMCPServerForTab(tab, name)
-	return err
+	if err != nil {
+		recordMCPFailure(tab.Ctrl, config.PluginEntry{Name: name}, err)
+		return err
+	}
+	a.mu.Lock()
+	delete(tab.disabledMCP, name)
+	a.mu.Unlock()
+	return nil
 }
 
 // ClearMCPServerAuthentication removes local auth-like config for one MCP and
@@ -1829,9 +1858,9 @@ func (a *App) connectConfiguredMCPServerForTab(tab *WorkspaceTab, name string) (
 	return 0, fmt.Errorf("no configured MCP server named %q", name)
 }
 
-// SetMCPServerTier persists how a configured MCP server should start on future
-// sessions. It does not tear down a connected server; the per-session toggle and
-// "connect now" remain separate controls.
+// SetMCPServerTier is kept for old desktop bindings. New config writes drop the
+// retired tier field, so this only affects the active session before the next
+// config reload.
 func (a *App) SetMCPServerTier(name, tier string) error {
 	if name == "codegraph" {
 		return a.setCodegraphTier(tier)
@@ -1878,9 +1907,6 @@ func (a *App) setCodegraphEnabled(enabled bool) error {
 	if err := cfg.SaveTo(path); err != nil {
 		return err
 	}
-	if err := a.syncProjectCodegraphOverride(cfg.Codegraph); err != nil {
-		return err
-	}
 	if enabled {
 		a.mu.Lock()
 		delete(tab.disabledMCP, "codegraph")
@@ -1917,9 +1943,6 @@ func (a *App) setCodegraphTier(tier string) error {
 	if err := cfg.SaveTo(path); err != nil {
 		return err
 	}
-	if err := a.syncProjectCodegraphOverride(cfg.Codegraph); err != nil {
-		return err
-	}
 	tab := a.activeTab()
 	if tab == nil || tab.Ctrl == nil {
 		return nil
@@ -1953,37 +1976,21 @@ func (a *App) desktopMCPServerForEdit(name string) (config.PluginEntry, bool, er
 }
 
 func (a *App) saveDesktopMCPServer(entry config.PluginEntry) error {
-	cfg, path, err := a.loadDesktopUserConfigForEdit()
-	if err != nil {
+	if err := config.UpsertMCPPlugin(entry); err != nil {
 		return err
 	}
-	if err := cfg.UpsertPlugin(entry); err != nil {
-		return err
-	}
-	if err := cfg.SaveTo(path); err != nil {
-		return err
-	}
-	_, err = a.removeProjectMCPOverride(entry.Name)
-	return err
+	// Project-level overrides are no longer supported; clean up legacy entries.
+	_, _ = a.removeProjectMCPOverride(entry.Name)
+	return nil
 }
 
 func (a *App) removeDesktopMCPServer(name string) (bool, error) {
-	removed := false
-	cfg, path, err := a.loadDesktopUserConfigForEdit()
+	found, err := config.RemoveMCPPlugin(name)
 	if err != nil {
 		return false, err
 	}
-	if cfg.RemovePlugin(name) {
-		removed = true
-		if err := cfg.SaveTo(path); err != nil {
-			return false, err
-		}
-	}
-	projectRemoved, err := a.removeProjectMCPOverride(name)
-	if err != nil {
-		return removed, err
-	}
-	return removed || projectRemoved, nil
+	projectRemoved, _ := a.removeProjectMCPOverride(name)
+	return found || projectRemoved, nil
 }
 
 func (a *App) removeProjectMCPOverride(name string) (bool, error) {
@@ -2008,23 +2015,6 @@ func (a *App) removeProjectMCPOverride(name string) (bool, error) {
 	return true, nil
 }
 
-func (a *App) syncProjectCodegraphOverride(c config.CodegraphConfig) error {
-	path := projectConfigPathForRoot(a.activeWorkspaceRoot())
-	userPath := config.UserConfigPath()
-	if path == "" || sameConfigPath(path, userPath) {
-		return nil
-	}
-	if _, err := os.Stat(path); err != nil {
-		if os.IsNotExist(err) {
-			return nil
-		}
-		return err
-	}
-	cfg := config.LoadForEdit(path)
-	cfg.Codegraph = c
-	return cfg.SaveTo(path)
-}
-
 func findPluginEntry(entries []config.PluginEntry, name string) (config.PluginEntry, bool) {
 	for _, p := range entries {
 		if p.Name == name {
@@ -2040,6 +2030,8 @@ func normalizeMCPTier(tier string) string {
 		return "eager"
 	case "background":
 		return "background"
+	case "":
+		return "background"
 	default:
 		return "lazy"
 	}
diff --git a/desktop/app_test.go b/desktop/app_test.go
index 28f7ca717..cd3ba4237 100644
--- a/desktop/app_test.go
+++ b/desktop/app_test.go
@@ -50,9 +50,30 @@ func isolateDesktopUserDirs(t *testing.T) string {
 	t.Setenv("USERPROFILE", home)
 	t.Setenv("XDG_CONFIG_HOME", xdg)
 	t.Setenv("AppData", appData)
+	t.Setenv("APPDATA", appData)
 	return home
 }
 
+func writeDesktopConfig(t *testing.T, body string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(config.UserConfigPath()), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(config.UserConfigPath(), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func writeDesktopMCP(t *testing.T, body string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(config.UserMCPConfigPath()), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(config.UserMCPConfigPath(), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
 func TestCommandsIncludesEffortNotThinking(t *testing.T) {
 	app := NewApp()
 	cmds := app.Commands()
@@ -174,7 +195,7 @@ close_behavior = "quit"
 	}
 }
 
-func TestSettingsSeedsMissingUserConfigFromLegacyProjectConfig(t *testing.T) {
+func TestSettingsIgnoresLegacyProjectConfigWhenUserConfigMissing(t *testing.T) {
 	isolateDesktopUserDirs(t)
 
 	project := t.TempDir()
@@ -201,8 +222,8 @@ close_behavior = "quit"
 	if got.ConfigPath != config.UserConfigPath() {
 		t.Fatalf("Settings configPath = %q, want user config %q", got.ConfigPath, config.UserConfigPath())
 	}
-	if got.DefaultModel != "legacy-provider/legacy-model" || got.DesktopLanguage != "zh" || got.DesktopTheme != "light" || got.DesktopThemeStyle != "glacier" || got.CloseBehavior != "quit" {
-		t.Fatalf("Settings did not seed from legacy project config: %+v", got)
+	if got.DefaultModel == "legacy-provider/legacy-model" || got.DesktopLanguage == "zh" || got.DesktopTheme == "light" || got.DesktopThemeStyle == "glacier" || got.CloseBehavior == "quit" {
+		t.Fatalf("Settings should ignore legacy project config: %+v", got)
 	}
 	if _, err := os.Stat(config.UserConfigPath()); !os.IsNotExist(err) {
 		t.Fatalf("Settings() should not write user config before an edit, stat err = %v", err)
@@ -211,8 +232,44 @@ close_behavior = "quit"
 		t.Fatalf("SetDesktopLanguage: %v", err)
 	}
 	userCfg := config.LoadForEdit(config.UserConfigPath())
-	if userCfg.DesktopLanguage() != "en" || userCfg.DesktopTheme() != "light" || userCfg.DesktopThemeStyle() != "glacier" || userCfg.DesktopCloseBehavior() != "quit" {
-		t.Fatalf("saved user config did not preserve seeded desktop prefs: lang:%q theme:%q style:%q close:%q", userCfg.DesktopLanguage(), userCfg.DesktopTheme(), userCfg.DesktopThemeStyle(), userCfg.DesktopCloseBehavior())
+	if userCfg.DesktopLanguage() != "en" || userCfg.DesktopTheme() == "light" || userCfg.DesktopThemeStyle() == "glacier" || userCfg.DesktopCloseBehavior() == "quit" {
+		t.Fatalf("saved user config should use global defaults plus the edit, not legacy project prefs: lang:%q theme:%q style:%q close:%q", userCfg.DesktopLanguage(), userCfg.DesktopTheme(), userCfg.DesktopThemeStyle(), userCfg.DesktopCloseBehavior())
+	}
+}
+
+func TestSettingsSubagentDefaultsRoundTrip(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	if err := os.MkdirAll(filepath.Dir(config.UserConfigPath()), 0o755); err != nil {
+		t.Fatalf("mkdir config dir: %v", err)
+	}
+	if err := os.WriteFile(config.UserConfigPath(), []byte(`
+default_model = "deepseek/deepseek-v4-flash"
+
+[[providers]]
+name = "deepseek"
+kind = "openai"
+base_url = "https://api.deepseek.com"
+models = ["deepseek-v4-flash", "deepseek-v4-pro"]
+default = "deepseek-v4-flash"
+`), 0o644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	app := NewApp()
+	if err := app.SetSubagentModel("deepseek/deepseek-v4-pro"); err != nil {
+		t.Fatalf("SetSubagentModel: %v", err)
+	}
+	if err := app.SetSubagentEffort("max"); err != nil {
+		t.Fatalf("SetSubagentEffort: %v", err)
+	}
+
+	got := app.Settings()
+	if got.SubagentModel != "deepseek/deepseek-v4-pro" || got.SubagentEffort != "max" {
+		t.Fatalf("subagent settings = model:%q effort:%q", got.SubagentModel, got.SubagentEffort)
+	}
+	cfg := config.LoadForEdit(config.UserConfigPath())
+	if cfg.Agent.SubagentModel != "deepseek/deepseek-v4-pro" || cfg.Agent.SubagentEffort != "max" {
+		t.Fatalf("saved config = model:%q effort:%q", cfg.Agent.SubagentModel, cfg.Agent.SubagentEffort)
 	}
 }
 
@@ -554,21 +611,20 @@ func TestForkCreatesActiveTabWithoutSwitchingSourceController(t *testing.T) {
 	}
 }
 
-func TestCapabilitiesShowsLazyMCPAsDeferredNotDisabled(t *testing.T) {
+func TestCapabilitiesShowsDefaultMCPAsInitializingNotDisabled(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "playwright"
 command = "npx"
 args = ["-y", "@playwright/mcp"]
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -581,8 +637,8 @@ args = ["-y", "@playwright/mcp"]
 	view := app.Capabilities()
 	for _, s := range view.Servers {
 		if s.Name == "playwright" {
-			if s.Status != "deferred" {
-				t.Fatalf("lazy MCP status = %q, want deferred; server = %+v", s.Status, s)
+			if s.Status != "initializing" {
+				t.Fatalf("default MCP status = %q, want initializing; server = %+v", s.Status, s)
 			}
 			return
 		}
@@ -611,8 +667,8 @@ func TestCapabilitiesShowsDefaultCodegraphDisabled(t *testing.T) {
 			if s.AutoStart {
 				t.Fatalf("codegraph autoStart = true, want false; server = %+v", s)
 			}
-			if s.Tier != "lazy" {
-				t.Fatalf("codegraph tier = %q, want lazy; server = %+v", s.Tier, s)
+			if s.Tier != "background" {
+				t.Fatalf("codegraph tier = %q, want background; server = %+v", s.Tier, s)
 			}
 			return
 		}
@@ -620,22 +676,21 @@ func TestCapabilitiesShowsDefaultCodegraphDisabled(t *testing.T) {
 	t.Fatalf("codegraph missing from Capabilities: %+v", view.Servers)
 }
 
-func TestCapabilitiesMarksDeferredRemoteMCPAuthPossible(t *testing.T) {
+func TestCapabilitiesMarksBackgroundRemoteMCPAuthPossible(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "dida"
 type = "http"
 url = "https://mcp.dida365.com"
 tier = "lazy"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -644,7 +699,7 @@ tier = "lazy"
 	view := app.Capabilities()
 	for _, s := range view.Servers {
 		if s.Name == "dida" {
-			if s.Status != "deferred" || s.AuthStatus != "possible" || s.AuthURL != "https://mcp.dida365.com" {
+			if s.Status != "initializing" || s.AuthStatus != "possible" || s.AuthURL != "https://mcp.dida365.com" {
 				t.Fatalf("dida auth diagnosis = %+v", s)
 			}
 			return
@@ -657,19 +712,18 @@ func TestCapabilitiesDoesNotMarkRemoteMCPWithAuthHeaderPossible(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "stripe"
 type = "http"
 url = "https://mcp.stripe.com"
 headers = { Authorization = "Bearer ${STRIPE_TOKEN}" }
 tier = "lazy"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -691,18 +745,17 @@ func TestCapabilitiesMarksAuthFailureRequired(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "figma"
 type = "http"
 url = "https://mcp.figma.com/mcp"
 tier = "lazy"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	host := plugin.NewHost()
 	host.RecordFailure(plugin.Spec{Name: "figma", Type: "http", URL: "https://mcp.figma.com/mcp"}, errors.New("connect: 401 unauthorized"))
@@ -726,10 +779,11 @@ func TestClearMCPServerAuthenticationClearsConfigAndFailure(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "figma"
 type = "http"
@@ -737,9 +791,7 @@ url = "https://mcp.figma.com/mcp?access_token=abc&workspace=main"
 headers = { Authorization = "Bearer ${FIGMA_TOKEN}", "X-Org" = "team" }
 env = { FIGMA_TOKEN = "${FIGMA_TOKEN}", DEBUG = "1" }
 tier = "lazy"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	host := plugin.NewHost()
 	host.RecordFailure(plugin.Spec{Name: "figma", Type: "http", URL: "https://mcp.figma.com/mcp"}, errors.New("connect: 401 unauthorized"))
@@ -776,8 +828,8 @@ tier = "lazy"
 	view := app.Capabilities()
 	for _, s := range view.Servers {
 		if s.Name == "figma" {
-			if s.Status != "deferred" || s.AuthStatus != "possible" {
-				t.Fatalf("figma should return to deferred possible auth: %+v", s)
+			if s.Status != "initializing" || s.AuthStatus != "possible" {
+				t.Fatalf("figma should return to background possible auth: %+v", s)
 			}
 			return
 		}
@@ -785,22 +837,22 @@ tier = "lazy"
 	t.Fatalf("figma MCP missing from Capabilities: %+v", view.Servers)
 }
 
-func TestUpdateMCPServerKeepsLazyMCPDeferred(t *testing.T) {
+func TestUpdateMCPServerMigratesLegacyTierToBackground(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "playwright"
 command = "npx"
 args = ["-y", "@playwright/mcp"]
 env = { TOKEN = "${PLAYWRIGHT_TOKEN}" }
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+tier = "lazy"
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -815,7 +867,6 @@ env = { TOKEN = "${PLAYWRIGHT_TOKEN}" }
 		Transport: "stdio",
 		Command:   "node",
 		Args:      []string{"server.js"},
-		Tier:      "lazy",
 	}); err != nil {
 		t.Fatalf("UpdateMCPServer: %v", err)
 	}
@@ -829,23 +880,21 @@ env = { TOKEN = "${PLAYWRIGHT_TOKEN}" }
 	if got := cfg.Plugins[0].Env["TOKEN"]; got != "${PLAYWRIGHT_TOKEN}" {
 		t.Fatalf("env TOKEN = %q, want preserved env", got)
 	}
-	userCfg := config.LoadForEdit(config.UserConfigPath())
-	userPlugin, ok := findPluginEntry(userCfg.Plugins, "playwright")
+	userPlugin, ok := findPluginEntry(cfg.Plugins, "playwright")
 	if !ok {
-		t.Fatalf("playwright should be migrated to user config: %+v", userCfg.Plugins)
+		t.Fatalf("playwright should be saved to mcp.toml: %+v", cfg.Plugins)
 	}
 	if userPlugin.Command != "node" || userPlugin.Env["TOKEN"] != "${PLAYWRIGHT_TOKEN}" {
 		t.Fatalf("user plugin after migration = %+v", userPlugin)
 	}
-	projectCfg := config.LoadForEdit(filepath.Join(dir, "reasonix.toml"))
-	if _, ok := findPluginEntry(projectCfg.Plugins, "playwright"); ok {
-		t.Fatalf("project plugin should be removed after desktop migration: %+v", projectCfg.Plugins)
+	if userPlugin.Tier != "" {
+		t.Fatalf("user plugin tier = %q, want migrated empty", userPlugin.Tier)
 	}
 	view := app.Capabilities()
 	for _, s := range view.Servers {
 		if s.Name == "playwright" {
-			if s.Status != "deferred" {
-				t.Fatalf("updated lazy MCP status = %q, want deferred; server = %+v", s.Status, s)
+			if s.Status != "failed" {
+				t.Fatalf("updated MCP status = %q, want failed after immediate reconnect attempt; server = %+v", s.Status, s)
 			}
 			if s.Command != "node" || len(s.Args) != 1 || s.Args[0] != "server.js" {
 				t.Fatalf("server command not refreshed: %+v", s)
@@ -856,21 +905,59 @@ env = { TOKEN = "${PLAYWRIGHT_TOKEN}" }
 	t.Fatalf("playwright MCP missing from Capabilities: %+v", view.Servers)
 }
 
-func TestUpdateMCPServerRecordsReconnectFailure(t *testing.T) {
+func TestUpdateMCPServerSplitsPastedCommandLine(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
-name = "broken"
+name = "playwright"
 command = "npx"
-tier = "lazy"
-`), 0o644); err != nil {
+args = ["-y", "@playwright/mcp"]
+`)
+
+	app := NewApp()
+	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
+	defer app.activeCtrl().Close()
+
+	if err := app.UpdateMCPServer("playwright", MCPServerInput{
+		Name:      "playwright",
+		Transport: "stdio",
+		Command:   "npx -y @modelcontextprotocol/server-filesystem .",
+	}); err != nil {
+		t.Fatalf("UpdateMCPServer: %v", err)
+	}
+	cfg, err := config.Load()
+	if err != nil {
 		t.Fatal(err)
 	}
+	p := cfg.Plugins[0]
+	if p.Command != "npx" {
+		t.Fatalf("command = %q, want npx", p.Command)
+	}
+	if got := strings.Join(p.Args, "\x00"); got != strings.Join([]string{"-y", "@modelcontextprotocol/server-filesystem", "."}, "\x00") {
+		t.Fatalf("args = %v", p.Args)
+	}
+}
+
+func TestUpdateMCPServerRecordsReconnectFailure(t *testing.T) {
+	isolateDesktopUserDirs(t)
+	dir := t.TempDir()
+	t.Chdir(dir)
+	writeDesktopConfig(t, `
+[codegraph]
+enabled = false
+`)
+	writeDesktopMCP(t, `
+[[plugins]]
+name = "broken"
+command = "npx"
+tier = "background"
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -880,7 +967,6 @@ tier = "lazy"
 		Name:      "broken",
 		Transport: "stdio",
 		Command:   "reasonix-missing-mcp-binary",
-		Tier:      "background",
 	}); err != nil {
 		t.Fatalf("UpdateMCPServer should persist config even when reconnect fails: %v", err)
 	}
@@ -891,8 +977,8 @@ tier = "lazy"
 	if got := cfg.Plugins[0].Command; got != "reasonix-missing-mcp-binary" {
 		t.Fatalf("updated command = %q, want missing binary", got)
 	}
-	if got := cfg.Plugins[0].Tier; got != "background" {
-		t.Fatalf("updated tier = %q, want background", got)
+	if got := cfg.Plugins[0].Tier; got != "" {
+		t.Fatalf("updated tier = %q, want migrated empty", got)
 	}
 	if !mcpFailed(app.activeCtrl(), "broken") {
 		t.Fatalf("Host.Failures() = %+v, want broken failure recorded", app.activeCtrl().Host().Failures())
@@ -916,17 +1002,16 @@ func TestSetMCPServerTierRecordsConnectFailure(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "broken"
 command = "reasonix-missing-mcp-binary"
 tier = "lazy"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -937,26 +1022,21 @@ tier = "lazy"
 	}()
 
 	if err := app.SetMCPServerTier("broken", "background"); err != nil {
-		t.Fatalf("SetMCPServerTier should persist tier even when immediate connect fails: %v", err)
+		t.Fatalf("SetMCPServerTier legacy binding: %v", err)
 	}
 	cfg, err := config.Load()
 	if err != nil {
 		t.Fatal(err)
 	}
-	if got := cfg.Plugins[0].Tier; got != "background" {
-		t.Fatalf("saved tier = %q, want background", got)
+	if got := cfg.Plugins[0].Tier; got != "" {
+		t.Fatalf("saved tier = %q, want migrated empty", got)
 	}
-	userCfg := config.LoadForEdit(config.UserConfigPath())
-	userPlugin, ok := findPluginEntry(userCfg.Plugins, "broken")
+	userPlugin, ok := findPluginEntry(cfg.Plugins, "broken")
 	if !ok {
-		t.Fatalf("broken should be migrated to user config: %+v", userCfg.Plugins)
+		t.Fatalf("broken should be saved to mcp.toml: %+v", cfg.Plugins)
 	}
-	if userPlugin.Tier != "background" {
-		t.Fatalf("user plugin tier = %q, want background", userPlugin.Tier)
-	}
-	projectCfg := config.LoadForEdit(filepath.Join(dir, "reasonix.toml"))
-	if _, ok := findPluginEntry(projectCfg.Plugins, "broken"); ok {
-		t.Fatalf("project plugin should be removed after desktop migration: %+v", projectCfg.Plugins)
+	if userPlugin.Tier != "" {
+		t.Fatalf("user plugin tier = %q, want migrated empty", userPlugin.Tier)
 	}
 	if !mcpFailed(app.activeCtrl(), "broken") {
 		t.Fatalf("Host.Failures() = %+v, want broken failure recorded", app.activeCtrl().Host().Failures())
@@ -977,21 +1057,16 @@ tier = "lazy"
 }
 
 func TestSetMCPServerTierPersistsCodegraphConfig(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
-	t.Setenv("USERPROFILE", t.TempDir())
-	t.Setenv("XDG_CONFIG_HOME", t.TempDir())
-	t.Setenv("AppData", t.TempDir())
+	isolateDesktopUserDirs(t)
 	t.Setenv("PATH", t.TempDir())
 	t.Setenv("REASONIX_CACHE_DIR", t.TempDir()) // isolate the codegraph bundle cache so Resolve fails deterministically
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
 auto_install = true
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -1007,15 +1082,15 @@ auto_install = true
 	if !cfg.Codegraph.Enabled {
 		t.Fatal("codegraph enabled = false, want true after selecting a startup tier")
 	}
-	if got := cfg.Codegraph.Tier; got != "background" {
-		t.Fatalf("codegraph tier = %q, want background", got)
+	if got := cfg.Codegraph.Tier; got != "" {
+		t.Fatalf("codegraph tier = %q, want migrated empty", got)
 	}
 	userCfg := config.LoadForEdit(config.UserConfigPath())
 	if !userCfg.Codegraph.Enabled {
 		t.Fatal("user codegraph enabled = false, want true after selecting a startup tier")
 	}
-	if got := userCfg.Codegraph.Tier; got != "background" {
-		t.Fatalf("user codegraph tier = %q, want background", got)
+	if got := userCfg.Codegraph.Tier; got != "" {
+		t.Fatalf("user codegraph tier = %q, want migrated empty", got)
 	}
 	if !mcpFailed(app.activeCtrl(), "codegraph") {
 		t.Fatalf("Host.Failures() = %+v, want codegraph failure recorded for missing runtime", app.activeCtrl().Host().Failures())
@@ -1039,13 +1114,11 @@ func TestSetMCPServerEnabledPersistsCodegraphOff(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = true
 tier = "lazy"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -1077,21 +1150,20 @@ tier = "lazy"
 	t.Fatalf("codegraph missing from Capabilities: %+v", view.Servers)
 }
 
-func TestCapabilitiesKeepsFailedMCPConfiguredTierAfterRestart(t *testing.T) {
+func TestCapabilitiesMigratesFailedMCPConfiguredTierAfterRestart(t *testing.T) {
 	isolateDesktopUserDirs(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile(filepath.Join(dir, "reasonix.toml"), []byte(`
+	writeDesktopConfig(t, `
 [codegraph]
 enabled = false
-
+`)
+	writeDesktopMCP(t, `
 [[plugins]]
 name = "broken"
 command = "reasonix-missing-mcp-binary"
 tier = "eager"
-`), 0o644); err != nil {
-		t.Fatal(err)
-	}
+`)
 
 	app := NewApp()
 	app.setTestCtrl(control.New(control.Options{Host: plugin.NewHost()}), "")
@@ -1108,8 +1180,8 @@ tier = "eager"
 			if s.Status != "failed" {
 				t.Fatalf("server status = %q, want failed; server = %+v", s.Status, s)
 			}
-			if s.Tier != "eager" {
-				t.Fatalf("server tier = %q, want eager so failed UI preserves the configured selection", s.Tier)
+			if s.Tier != "background" {
+				t.Fatalf("server tier = %q, want migrated background default", s.Tier)
 			}
 			if !s.Configured {
 				t.Fatalf("server configured = false, want true; server = %+v", s)
diff --git a/desktop/frontend/src/components/CapabilitiesPanel.tsx b/desktop/frontend/src/components/CapabilitiesPanel.tsx
index 6b9d35d6f..ab9a11cca 100644
--- a/desktop/frontend/src/components/CapabilitiesPanel.tsx
+++ b/desktop/frontend/src/components/CapabilitiesPanel.tsx
@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useId, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { asArray } from "../lib/array";
 import { app, openExternal } from "../lib/bridge";
 import { useT } from "../lib/i18n";
@@ -140,6 +140,11 @@ export function CapabilitiesPanel({
               ✕
             </button>
           </Tooltip>
+          <Tooltip label={t("caps.refresh")}>
+            <button className="chip" disabled={busy} onClick={() => void reload()}>
+              ↻
+            </button>
+          </Tooltip>
         </header>
 
         {!view ? (
@@ -181,9 +186,8 @@ export function CapabilitiesPanel({
                     servers={serverGroups.failed}
                     expanded={expandedErrors}
                     onToggle={toggleError}
-                    onRetry={(name) => void mutate(() => app.RetryMCPServer(name))}
+                    onRetry={(name) => void mutate(() => app.ReconnectMCPServer(name))}
                     onConfirmClearAuth={(name) => void mutate(() => app.ClearMCPServerAuthentication(name))}
-                    onSetTier={(name, tier) => void mutate(() => app.SetMCPServerTier(name, tier))}
                     onConfirm={(name) => void mutate(() => app.RemoveMCPServer(name))}
                     busy={busy}
                   />
@@ -202,10 +206,10 @@ export function CapabilitiesPanel({
                     setEditing(name);
                   }}
                   onCancelEdit={() => setEditing(null)}
-                  onRetry={(name) => void mutate(() => app.RetryMCPServer(name))}
+                  onRetry={(name) => void mutate(() => app.ReconnectMCPServer(name))}
+                  onReconnect={(name) => void mutate(() => app.ReconnectMCPServer(name))}
                   onConfirmClearAuth={(name) => void mutate(() => app.ClearMCPServerAuthentication(name))}
                   onToggle={(name, on) => void mutate(() => app.SetMCPServerEnabled(name, on))}
-                  onSetTier={(name, tier) => void mutate(() => app.SetMCPServerTier(name, tier))}
                   onUpdate={(name, input) =>
                     void mutate(() => app.UpdateMCPServer(name, input)).then((ok) => {
                       if (ok) setEditing(null);
@@ -594,9 +598,9 @@ function ServerGroup({
   onEdit,
   onCancelEdit,
   onRetry,
+  onReconnect,
   onConfirmClearAuth,
   onToggle,
-  onSetTier,
   onUpdate,
   onToggleDetails,
   onToggleTools,
@@ -610,9 +614,9 @@ function ServerGroup({
   onEdit: (name: string) => void;
   onCancelEdit: () => void;
   onRetry: (name: string) => void;
+  onReconnect: (name: string) => void;
   onConfirmClearAuth: (name: string) => void;
   onToggle: (name: string, on: boolean) => void;
-  onSetTier: (name: string, tier: string) => void;
   onUpdate: (name: string, input: MCPServerInput) => void;
   onToggleDetails: (name: string) => void;
   onToggleTools: (name: string) => void;
@@ -632,9 +636,9 @@ function ServerGroup({
           onEdit={() => onEdit(s.name)}
           onCancelEdit={onCancelEdit}
           onRetry={() => onRetry(s.name)}
+          onReconnect={() => onReconnect(s.name)}
           onConfirmClearAuth={() => onConfirmClearAuth(s.name)}
           onToggle={(on) => onToggle(s.name, on)}
-          onSetTier={(tier) => onSetTier(s.name, tier)}
           onUpdate={(input) => onUpdate(s.name, input)}
           onToggleDetails={() => onToggleDetails(s.name)}
           onToggleTools={() => onToggleTools(s.name)}
@@ -651,7 +655,6 @@ function FailedServersNotice({
   onToggle,
   onRetry,
   onConfirmClearAuth,
-  onSetTier,
   onConfirm,
 }: {
   servers: ServerView[];
@@ -660,7 +663,6 @@ function FailedServersNotice({
   onToggle: (name: string) => void;
   onRetry: (name: string) => void;
   onConfirmClearAuth: (name: string) => void;
-  onSetTier: (name: string, tier: string) => void;
   onConfirm: (name: string) => void;
 }) {
   const t = useT();
@@ -677,7 +679,6 @@ function FailedServersNotice({
           const open = expanded.has(s.name);
           const error = s.error || t("caps.failed");
           const actionLabel = serverActionLabel(s, t);
-          const canConfigure = s.configured;
           const handlePrimaryAction = () => {
             if (shouldOpenAuth(s)) {
               openExternal((s.authUrl || "").trim());
@@ -721,11 +722,6 @@ function FailedServersNotice({
                   />
                 )}
               </div>
-              {canConfigure && (
-                <div className="cap-failure__mode">
-                  <AutoConnectControls tier={s.tier || "lazy"} busy={busy} onTierChange={(tier) => onSetTier(s.name, tier)} />
-                </div>
-              )}
               {open && (
                 <div className="cap-failure__logbox">
                   <div className="cap-failure__logbar">
@@ -755,9 +751,9 @@ function ServerRow({
   onEdit,
   onCancelEdit,
   onRetry,
+  onReconnect,
   onConfirmClearAuth,
   onToggle,
-  onSetTier,
   onUpdate,
   onToggleDetails,
   onToggleTools,
@@ -771,9 +767,9 @@ function ServerRow({
   onEdit: () => void;
   onCancelEdit: () => void;
   onRetry: () => void;
+  onReconnect: () => void;
   onConfirmClearAuth: () => void;
   onToggle: (on: boolean) => void;
-  onSetTier: (tier: string) => void;
   onUpdate: (input: MCPServerInput) => void;
   onToggleDetails: () => void;
   onToggleTools: () => void;
@@ -856,8 +852,8 @@ function ServerRow({
           busy={busy}
           onConfirm={onConfirm}
           onConnectNow={onRetry}
+          onReconnect={onReconnect}
           onConfirmClearAuth={onConfirmClearAuth}
-          onSetTier={onSetTier}
           toolsExpanded={toolsExpanded}
           editing={editing}
           onEdit={onEdit}
@@ -876,8 +872,8 @@ function ServerDetails({
   busy,
   onConfirm,
   onConnectNow,
+  onReconnect,
   onConfirmClearAuth,
-  onSetTier,
   toolsExpanded,
   editing,
   onEdit,
@@ -890,8 +886,8 @@ function ServerDetails({
   busy: boolean;
   onConfirm: () => void;
   onConnectNow: () => void;
+  onReconnect: () => void;
   onConfirmClearAuth: () => void;
-  onSetTier: (tier: string) => void;
   toolsExpanded: boolean;
   editing: boolean;
   onEdit: () => void;
@@ -901,9 +897,9 @@ function ServerDetails({
 }) {
   const t = useT();
   const command = serverCommand(s);
-  const canConfigure = s.configured;
   const canEditConfig = s.configured && !s.builtIn;
   const canConnectNow = s.status === "deferred" || s.status === "disabled";
+  const canReconnect = s.status === "connected";
   const canShowTools = (s.tools ?? 0) > 0 || (tools?.length ?? 0) > 0;
   const showClearAuth = canClearAuth(s);
   const authLabel = serverAuthLabel(s, t);
@@ -931,9 +927,6 @@ function ServerDetails({
             <span className="cap-detail__value">{authLabel}</span>
           </div>
         )}
-        {canConfigure && (
-          <AutoConnectControls tier={s.tier || "lazy"} busy={busy} onTierChange={onSetTier} />
-        )}
         {command && (
           <div className="cap-detail cap-detail--wide">
             <span className="cap-detail__label">{s.transport === "stdio" ? t("caps.command") : t("caps.url")}</span>
@@ -953,6 +946,11 @@ function ServerDetails({
             {t("caps.connectNow")}
           </button>
         )}
+        {canReconnect && (
+          <button className="btn btn--small" disabled={busy} onClick={onReconnect}>
+            {t("caps.reconnect")}
+          </button>
+        )}
         {canShowTools && (
           <button className="btn btn--small" disabled={busy} onClick={onToggleTools} aria-expanded={toolsExpanded}>
             {toolsExpanded ? t("caps.hideTools") : t("caps.showTools")}
@@ -1019,7 +1017,6 @@ function EditServerForm({
   const [command, setCommand] = useState(initialTransport === "stdio" ? serverCommand(s) : "");
   const [url, setUrl] = useState(initialTransport === "stdio" ? "" : s.url || serverCommand(s));
   const [env, setEnv] = useState("");
-  const [tier, setTier] = useState(s.tier || "lazy");
   const isStdio = transport === "stdio";
   const ready = isStdio ? command.trim() !== "" : url.trim() !== "";
 
@@ -1033,7 +1030,6 @@ function EditServerForm({
       args: isStdio ? parts.slice(1) : [],
       url: isStdio ? "" : url.trim(),
       env: envText === "" ? null : parseEnvText(envText),
-      tier,
     });
   };
 
@@ -1063,7 +1059,6 @@ function EditServerForm({
             <input className="mem-input" value={url} disabled={busy} onChange={(e) => setUrl(e.target.value)} placeholder={t("caps.urlPlaceholder")} />
           </label>
         )}
-        <AutoConnectControls tier={tier} busy={busy} onTierChange={setTier} />
         <label className="cap-detail cap-detail--wide">
           <span className="cap-detail__label">{t("caps.envLabel")}</span>
           <textarea className="mem-textarea cap-config-edit__env" value={env} disabled={busy} onChange={(e) => setEnv(e.target.value)} placeholder={t("caps.envPlaceholder")} spellCheck={false} />
@@ -1088,60 +1083,11 @@ function EditServerForm({
   );
 }
 
-function AutoConnectControls({
-  tier,
-  busy,
-  onTierChange,
-}: {
-  tier: string;
-  busy: boolean;
-  onTierChange: (tier: string) => void;
-}) {
-  const t = useT();
-  const groupId = useId();
-  const normalized = normalizeTierValue(tier);
-  const options = [
-    { tier: "lazy", label: t("caps.launchLazy"), hint: t("caps.launchLazyHint") },
-    { tier: "background", label: t("caps.launchBackground"), hint: t("caps.launchBackgroundHint") },
-    { tier: "eager", label: t("caps.launchEager"), hint: t("caps.launchEagerHint") },
-  ];
-  return (
-    <fieldset className="cap-detail cap-detail--wide cap-connection-mode">
-      <legend className="cap-detail__label">{t("caps.launchMode")}</legend>
-      <div className="cap-connection-options">
-        {options.map((option) => (
-          <label
-            className={`cap-connection-option${normalized === option.tier ? " cap-connection-option--selected" : ""}${busy ? " cap-connection-option--disabled" : ""}`}
-            key={option.tier}
-          >
-            <input
-              type="radio"
-              name={`mcp-connection-tier-${groupId}`}
-              value={option.tier}
-              checked={normalized === option.tier}
-              disabled={busy}
-              onChange={() => onTierChange(option.tier)}
-            />
-            <span className="cap-connection-option__text">
-              <span className="cap-connection-option__label">{option.label}</span>
-              <span className="cap-connection-option__hint">{option.hint}</span>
-            </span>
-          </label>
-        ))}
-      </div>
-    </fieldset>
-  );
-}
-
 function serverCommand(s: ServerView): string {
   if (s.transport === "stdio") return [s.command, ...(s.args ?? [])].filter(Boolean).join(" ").trim();
   return (s.url || "").trim();
 }
 
-function normalizeTierValue(tier: string): string {
-  return tier === "background" || tier === "eager" ? tier : "lazy";
-}
-
 function normalizeTransportValue(transport: string): string {
   return transport === "http" || transport === "sse" ? transport : "stdio";
 }
@@ -1313,7 +1259,6 @@ function AddServerForm({
   const [command, setCommand] = useState("");
   const [url, setUrl] = useState("");
   const [env, setEnv] = useState("");
-  const [tier, setTier] = useState("lazy");
 
   const isStdio = transport === "stdio";
   const ready = name.trim() !== "" && (isStdio ? command.trim() !== "" : url.trim() !== "");
@@ -1332,7 +1277,6 @@ function AddServerForm({
       args: isStdio ? parts.slice(1) : [],
       url: isStdio ? "" : url.trim(),
       env: envMap,
-      tier,
     });
   };
 
@@ -1350,7 +1294,6 @@ function AddServerForm({
       ) : (
         <input className="mem-input" placeholder={t("caps.urlPlaceholder")} value={url} onChange={(e) => setUrl(e.target.value)} />
       )}
-      <AutoConnectControls tier={tier} busy={busy} onTierChange={setTier} />
       <label className="set-label">{t("caps.envLabel")}</label>
       <textarea className="mem-textarea" value={env} onChange={(e) => setEnv(e.target.value)} placeholder={t("caps.envPlaceholder")} spellCheck={false} />
       <div className="prov-card__actions">
diff --git a/desktop/frontend/src/components/SettingsPanel.tsx b/desktop/frontend/src/components/SettingsPanel.tsx
index fba73a7d2..f1d226c70 100644
--- a/desktop/frontend/src/components/SettingsPanel.tsx
+++ b/desktop/frontend/src/components/SettingsPanel.tsx
@@ -251,6 +251,8 @@ function normalizeSettingsView(view: SettingsView | null | undefined): SettingsV
   const agent = view.agent ?? { temperature: 0, maxSteps: 0, systemPrompt: "" };
   return {
     ...view,
+    subagentModel: view.subagentModel ?? "",
+    subagentEffort: view.subagentEffort ?? "",
     providers: asArray(view.providers).map((p) => ({ ...p, models: asArray(p.models) })),
     providerKinds: asArray(view.providerKinds),
     permissions: {
@@ -473,6 +475,7 @@ function ModelsSection({ s, busy, apply, onManageProviders }: SectionProps & { o
   const refs = allRefs(s);
   const defaultRef = toRef(s.defaultModel, s);
   const plannerRef = toRef(s.plannerModel, s);
+  const subagentRef = toRef(s.subagentModel, s);
   const [defaultProvider, defaultModel] = defaultRef.split("/");
   const plannerModeDetail = plannerRef
     ? t("settings.plannerDualDetail", { planner: plannerRef, executor: defaultRef || t("common.none") })
@@ -520,6 +523,41 @@ function ModelsSection({ s, busy, apply, onManageProviders }: SectionProps & { o
         </select>
       </div>
 
+      <div className="set-row">
+        <label className="set-label">{t("settings.subagentModel")}</label>
+        <select
+          className="mem-select set-grow"
+          value={subagentRef}
+          disabled={busy}
+          onChange={(e) => void apply(() => app.SetSubagentModel(e.target.value))}
+        >
+          <option value="">{t("settings.subagentModelDefault")}</option>
+          {refs.map((r) => (
+            <option key={r} value={r}>
+              {r}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      <div className="set-row">
+        <label className="set-label">{t("settings.subagentEffort")}</label>
+        <select
+          className="mem-select set-grow"
+          value={s.subagentEffort || ""}
+          disabled={busy}
+          onChange={(e) => void apply(() => app.SetSubagentEffort(e.target.value))}
+        >
+          <option value="">{t("settings.subagentEffortDefault")}</option>
+          {EFFORT_PRESETS.map((level) => (
+            <option key={level} value={level}>
+              {level}
+            </option>
+          ))}
+        </select>
+      </div>
+      <div className="mem-hint">{t("settings.subagentHint")}</div>
+
       <div className="settings-model-card">
         <div>
           <span>{t("settings.activeProvider")}</span>
@@ -531,6 +569,11 @@ function ModelsSection({ s, busy, apply, onManageProviders }: SectionProps & { o
           <strong>{plannerRef ? t("settings.plannerDual") : t("settings.plannerSingle")}</strong>
           <small>{plannerModeDetail}</small>
         </div>
+        <div>
+          <span>{t("settings.subagentDefaults")}</span>
+          <strong>{subagentRef || t("common.auto")}</strong>
+          <small>{s.subagentEffort ? `effort ${s.subagentEffort}` : t("common.auto")}</small>
+        </div>
       </div>
 
       <div className="settings-summary-grid">
diff --git a/desktop/frontend/src/components/ToolCard.tsx b/desktop/frontend/src/components/ToolCard.tsx
index 1970b9c89..68406fb34 100644
--- a/desktop/frontend/src/components/ToolCard.tsx
+++ b/desktop/frontend/src/components/ToolCard.tsx
@@ -24,6 +24,8 @@ import type { Item } from "../lib/useController";
 
 type ToolItem = Extract<Item, { kind: "tool" }>;
 
+const SUBAGENT_TOOLS = new Set(["task", "run_skill", "explore", "research", "review", "security_review"]);
+
 const ICONS: Record<string, LucideIcon> = {
   edit_file: FilePen,
   multi_edit: FilePen,
@@ -73,6 +75,10 @@ export const ToolCard = memo(function ToolCard({ item, subcalls }: { item: ToolI
   const Icon = ICONS[item.name] ?? Wrench;
   const nested = subcalls ?? [];
   const hasNested = nested.length > 0;
+  const profileText =
+    SUBAGENT_TOOLS.has(item.name) && item.profile
+      ? [item.profile.model, item.profile.effort ? `effort ${item.profile.effort}` : ""].filter(Boolean).join(" · ")
+      : "";
 
   // A task's summary is its step count; everything else derives from the result.
   const summary =
@@ -123,6 +129,7 @@ export const ToolCard = memo(function ToolCard({ item, subcalls }: { item: ToolI
         <Icon className="tool__icon" size={14} />
         <span className="tool__name">{item.name}</span>
         {subject && <span className="tool__subject">{subject}</span>}
+        {profileText && <span className="tool__profile">{profileText}</span>}
         <span className="tool__meta">
           <StatusGlyph status={item.status} />
         </span>
diff --git a/desktop/frontend/src/lib/bridge.ts b/desktop/frontend/src/lib/bridge.ts
index 369554972..552bb676a 100644
--- a/desktop/frontend/src/lib/bridge.ts
+++ b/desktop/frontend/src/lib/bridge.ts
@@ -127,7 +127,7 @@ export interface AppBindings {
   AddMCPServer(input: MCPServerInput): Promise<number>;
   UpdateMCPServer(name: string, input: MCPServerInput): Promise<void>;
   RemoveMCPServer(name: string): Promise<void>;
-  RetryMCPServer(name: string): Promise<void>;
+  ReconnectMCPServer(name: string): Promise<void>;
   ClearMCPServerAuthentication(name: string): Promise<void>;
   PickSkillFolder(): Promise<string>;
   AddSkillPath(path: string): Promise<void>;
@@ -163,6 +163,8 @@ export interface AppBindings {
   Settings(): Promise<SettingsView>;
   SetDefaultModel(ref: string): Promise<void>;
   SetPlannerModel(ref: string): Promise<void>;
+  SetSubagentModel(ref: string): Promise<void>;
+  SetSubagentEffort(level: string): Promise<void>;
   SetAutoPlan(mode: string): Promise<void>;
   SaveProvider(p: ProviderView): Promise<void>;
   DeleteProvider(name: string): Promise<void>;
@@ -376,7 +378,7 @@ function makeMockApp(): AppBindings {
       builtIn: true,
       configured: true,
       autoStart: false,
-      tier: "lazy",
+      tier: "background",
       tools: 0,
       prompts: 0,
       resources: 0,
@@ -387,14 +389,14 @@ function makeMockApp(): AppBindings {
         { name: "node", description: "Inspect a specific graph node." },
       ],
     },
-    { name: "github", transport: "stdio", status: "connected", configured: true, autoStart: true, tier: "lazy", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], tools: 12, prompts: 2, resources: 0 },
+    { name: "github", transport: "stdio", status: "connected", configured: true, autoStart: true, tier: "background", command: "npx", args: ["-y", "@modelcontextprotocol/server-github"], tools: 12, prompts: 2, resources: 0 },
     {
       name: "linear",
       transport: "http",
-      status: "deferred",
+      status: "initializing",
       configured: true,
       autoStart: true,
-      tier: "lazy",
+      tier: "background",
       url: "https://mcp.linear.app/mcp",
       authStatus: "possible",
       authUrl: "https://mcp.linear.app/mcp",
@@ -412,7 +414,7 @@ function makeMockApp(): AppBindings {
         { name: "search", description: "Search Linear workspace objects." },
       ],
     },
-    { name: "figma", transport: "http", status: "failed", configured: true, autoStart: true, tier: "lazy", url: "https://mcp.figma.com/mcp", authStatus: "required", authUrl: "https://mcp.figma.com/mcp", tools: 0, prompts: 0, resources: 0, error: "connect: 401 unauthorized" },
+    { name: "figma", transport: "http", status: "failed", configured: true, autoStart: true, tier: "background", url: "https://mcp.figma.com/mcp", authStatus: "required", authUrl: "https://mcp.figma.com/mcp", tools: 0, prompts: 0, resources: 0, error: "connect: 401 unauthorized" },
   ];
   const capSkills: SkillView[] = [
     { name: "explore", description: "Investigate the codebase in an isolated subagent", scope: "builtin", runAs: "subagent", enabled: true },
@@ -517,6 +519,8 @@ function makeMockApp(): AppBindings {
   const settings: SettingsView = {
     defaultModel: "deepseek-flash",
     plannerModel: "",
+    subagentModel: "",
+    subagentEffort: "",
     autoPlan: "off",
     providers: [
       { name: "deepseek-flash", kind: "openai", baseUrl: "https://api.deepseek.com", models: ["deepseek-v4-flash"], default: "deepseek-v4-flash", apiKeyEnv: "DEEPSEEK_API_KEY", keySet: true, balanceUrl: "https://api.deepseek.com/user/balance", contextWindow: 1_000_000, supportedEfforts: [], defaultEffort: "" },
@@ -1046,7 +1050,7 @@ function makeMockApp(): AppBindings {
         status: "connected",
         configured: true,
         autoStart: true,
-        tier: input.tier || "lazy",
+        tier: "background",
         command: input.command,
         args: input.args,
         url: input.url,
@@ -1063,14 +1067,13 @@ function makeMockApp(): AppBindings {
     async UpdateMCPServer(name: string, input: MCPServerInput) {
       capServers = capServers.map((s) => {
         if (s.name !== name) return s;
-        const connected = s.status === "connected" || s.status === "failed" || input.tier !== "lazy";
+        const connected = s.status === "connected" || s.status === "failed" || s.tier !== "lazy";
         const nextStatus = s.status === "disabled" ? "disabled" : connected ? "connected" : "deferred";
         const nextTools = nextStatus === "connected" ? s.tools || (input.transport === "stdio" ? 3 : 5) : 0;
         return {
           ...s,
           transport: input.transport,
           status: nextStatus,
-          tier: input.tier || "lazy",
           command: input.transport === "stdio" ? input.command : "",
           args: input.transport === "stdio" ? input.args : [],
           url: input.transport === "stdio" ? "" : input.url,
@@ -1085,9 +1088,15 @@ function makeMockApp(): AppBindings {
     async RemoveMCPServer(name: string) {
       capServers = capServers.filter((s) => s.name !== name);
     },
-    async RetryMCPServer(name: string) {
+    async ReconnectMCPServer(name: string) {
       capServers = capServers.map((s) =>
-        s.name === name ? { ...s, status: "connected", tools: s.tools || 4, error: undefined, authStatus: undefined, authUrl: undefined } : s,
+        s.name === name
+          ? { ...s, status: "initializing", error: undefined, authStatus: undefined, authUrl: undefined }
+          : s,
+      );
+      await new Promise((r) => setTimeout(r, 400));
+      capServers = capServers.map((s) =>
+        s.name === name ? { ...s, status: "connected", tools: s.tools || 4 } : s,
       );
     },
     async ClearMCPServerAuthentication(name: string) {
@@ -1348,6 +1357,12 @@ function makeMockApp(): AppBindings {
     async SetPlannerModel(ref: string) {
       settings.plannerModel = ref;
     },
+    async SetSubagentModel(ref: string) {
+      settings.subagentModel = ref;
+    },
+    async SetSubagentEffort(level: string) {
+      settings.subagentEffort = level;
+    },
     async SetAutoPlan(mode: string) {
       settings.autoPlan = mode;
     },
diff --git a/desktop/frontend/src/lib/types.ts b/desktop/frontend/src/lib/types.ts
index 5b12e7b9c..725a7dad0 100644
--- a/desktop/frontend/src/lib/types.ts
+++ b/desktop/frontend/src/lib/types.ts
@@ -26,6 +26,11 @@ export interface WireCompaction {
   archive?: string; // done: archive path, if any
 }
 
+export interface WireProfile {
+  model?: string;
+  effort?: string;
+}
+
 export interface WireTool {
   id?: string;
   name: string;
@@ -36,6 +41,7 @@ export interface WireTool {
   truncated?: boolean;
   partial?: boolean; // an early dispatch (name only) — a full one with args follows
   parentId?: string; // set on a sub-agent's calls — the parent `task` call's id
+  profile?: WireProfile; // subagent model/effort resolved for this call
 }
 
 export interface WireUsage {
@@ -355,7 +361,6 @@ export interface MCPServerInput {
   args: string[];
   url: string;
   env?: Record<string, string> | null;
-  tier: string;
 }
 
 export interface ModelInfo {
@@ -484,6 +489,8 @@ export interface AgentView {
 export interface SettingsView {
   defaultModel: string;
   plannerModel: string;
+  subagentModel: string;
+  subagentEffort: string;
   autoPlan: string;
   providers: ProviderView[];
   permissions: PermissionsView;
diff --git a/desktop/frontend/src/lib/useController.ts b/desktop/frontend/src/lib/useController.ts
index 66890acda..72dded2e5 100644
--- a/desktop/frontend/src/lib/useController.ts
+++ b/desktop/frontend/src/lib/useController.ts
@@ -57,6 +57,7 @@ export type Item =
       truncated?: boolean;
       isShell?: boolean; // true for !-prefix shell commands (controls default expand)
       parentId?: string; // a sub-agent call nests under the `task` call with this id
+      profile?: { model?: string; effort?: string }; // subagent model/effort from tool event
     };
 
 interface State {
@@ -179,10 +180,10 @@ function applyEvent(s: State, e: WireEvent): State {
       if (idx >= 0) {
         const next = [...s.items];
         const it = next[idx];
-        if (it.kind === "tool") next[idx] = { ...it, name: t.name, args: t.args ? t.args : it.args, readOnly: t.readOnly };
+        if (it.kind === "tool") next[idx] = { ...it, name: t.name, args: t.args ? t.args : it.args, readOnly: t.readOnly, profile: t.profile ?? it.profile };
         return { ...s, items: next };
       }
-      return { ...s, seq: s.seq + 1, items: [...s.items, { kind: "tool", id, name: t.name, args: t.args ?? "", readOnly: t.readOnly, status: "running", isShell: id.startsWith("shell-"), parentId: t.parentId }] };
+      return { ...s, seq: s.seq + 1, items: [...s.items, { kind: "tool", id, name: t.name, args: t.args ?? "", readOnly: t.readOnly, status: "running", isShell: id.startsWith("shell-"), parentId: t.parentId, profile: t.profile }] };
     }
     case "tool_result": {
       const t = e.tool;
diff --git a/desktop/frontend/src/locales/en.ts b/desktop/frontend/src/locales/en.ts
index 92c7393b0..429fcb3d3 100644
--- a/desktop/frontend/src/locales/en.ts
+++ b/desktop/frontend/src/locales/en.ts
@@ -16,6 +16,7 @@ export const en = {
   "common.expand": "Expand",
   "common.collapse": "Collapse",
   "common.none": "none",
+  "common.auto": "auto",
   "common.busyHint": "Finish or stop the current turn first",
   "common.loading": "Loading…",
 
@@ -145,13 +146,8 @@ export const en = {
   "caps.envLabel": "Environment (optional)",
   "caps.envPlaceholder": "KEY=VALUE, one per line",
   "caps.status": "Status",
-  "caps.launchMode": "Connection mode",
-  "caps.launchLazy": "Connect automatically when this MCP is used",
-  "caps.launchLazyHint": "Do not preconnect; connect the first time the model needs this MCP tool.",
-  "caps.launchBackground": "Connect in background after session start",
-  "caps.launchBackgroundHint": "Start connecting after a new session begins without blocking chat.",
-  "caps.launchEager": "Connect before the session starts",
-  "caps.launchEagerHint": "Wait for this MCP connection before the new session can begin.",
+  "caps.refresh": "Refresh MCP status",
+  "caps.reconnect": "Reconnect",
   "caps.command": "Command",
   "caps.url": "URL",
   "caps.envKeys": "Environment",
@@ -436,6 +432,12 @@ export const en = {
   "settings.defaultModel": "Default model",
   "settings.plannerModel": "Dedicated planner model",
   "settings.plannerNone": "Use current model (single model)",
+  "settings.subagentDefaults": "Subagent defaults",
+  "settings.subagentModel": "Subagent model",
+  "settings.subagentModelDefault": "Use current/default model",
+  "settings.subagentEffort": "Subagent effort",
+  "settings.subagentEffortDefault": "auto (provider default)",
+  "settings.subagentHint": "Applies to task and runAs=subagent skills unless a tool call or skill-specific config overrides it.",
   "settings.autoPlan": "Automatic plan mode",
   "settings.autoPlan.off": "Off",
   "settings.autoPlan.on": "On",
diff --git a/desktop/frontend/src/locales/zh.ts b/desktop/frontend/src/locales/zh.ts
index 329512964..ade67c644 100644
--- a/desktop/frontend/src/locales/zh.ts
+++ b/desktop/frontend/src/locales/zh.ts
@@ -17,6 +17,7 @@ export const zh: Record<DictKey, string> = {
   "common.expand": "展开",
   "common.collapse": "收起",
   "common.none": "无",
+  "common.auto": "自动",
   "common.busyHint": "请先完成或停止当前回合",
   "common.loading": "加载中…",
 
@@ -146,13 +147,8 @@ export const zh: Record<DictKey, string> = {
   "caps.envLabel": "环境变量（可选）",
   "caps.envPlaceholder": "KEY=VALUE，每行一个",
   "caps.status": "状态",
-  "caps.launchMode": "连接方式",
-  "caps.launchLazy": "用到该 MCP 时自动连接",
-  "caps.launchLazyHint": "不预先连接；模型第一次需要该 MCP 工具时再连接。",
-  "caps.launchBackground": "会话开始后后台连接",
-  "caps.launchBackgroundHint": "新会话开始后自动连接，不阻塞聊天。",
-  "caps.launchEager": "会话开始时先连接",
-  "caps.launchEagerHint": "新会话开始时等待该 MCP 连接完成。",
+  "caps.refresh": "刷新 MCP 状态",
+  "caps.reconnect": "重新连接",
   "caps.command": "命令",
   "caps.url": "URL",
   "caps.envKeys": "环境变量",
@@ -437,6 +433,12 @@ export const zh: Record<DictKey, string> = {
   "settings.defaultModel": "默认模型",
   "settings.plannerModel": "独立规划模型",
   "settings.plannerNone": "使用当前模型（单模型）",
+  "settings.subagentDefaults": "子代理默认值",
+  "settings.subagentModel": "子代理模型",
+  "settings.subagentModelDefault": "使用当前/默认模型",
+  "settings.subagentEffort": "子代理 effort",
+  "settings.subagentEffortDefault": "auto（模型服务默认）",
+  "settings.subagentHint": "作用于 task 和 runAs=subagent skills；工具调用参数或单个 skill 配置会覆盖它。",
   "settings.autoPlan": "自动计划模式",
   "settings.autoPlan.off": "关闭",
   "settings.autoPlan.on": "开启",
diff --git a/desktop/frontend/src/styles.css b/desktop/frontend/src/styles.css
index 1a13a17cb..20e8f5713 100644
--- a/desktop/frontend/src/styles.css
+++ b/desktop/frontend/src/styles.css
@@ -1492,6 +1492,15 @@ a[href] {
   white-space: nowrap;
   min-width: 0;
 }
+.tool__profile {
+  font-family: var(--mono);
+  font-size: var(--font-caption);
+  color: var(--fg-faint);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  min-width: 0;
+}
 .tool__meta {
   margin-left: auto;
   display: flex;
diff --git a/desktop/settings_app.go b/desktop/settings_app.go
index 2fff71517..eda85170a 100644
--- a/desktop/settings_app.go
+++ b/desktop/settings_app.go
@@ -74,6 +74,8 @@ type AgentView struct {
 type SettingsView struct {
 	DefaultModel      string          `json:"defaultModel"`
 	PlannerModel      string          `json:"plannerModel"`
+	SubagentModel     string          `json:"subagentModel"`
+	SubagentEffort    string          `json:"subagentEffort"`
 	AutoPlan          string          `json:"autoPlan"`
 	Providers         []ProviderView  `json:"providers"`
 	Permissions       PermissionsView `json:"permissions"`
@@ -127,10 +129,12 @@ func (a *App) Settings() SettingsView {
 		bash = "enforce"
 	}
 	v := SettingsView{
-		DefaultModel: cfg.DefaultModel,
-		PlannerModel: cfg.Agent.PlannerModel,
-		AutoPlan:     desktopAutoPlanMode(cfg.Agent.AutoPlan),
-		Providers:    []ProviderView{},
+		DefaultModel:   cfg.DefaultModel,
+		PlannerModel:   cfg.Agent.PlannerModel,
+		SubagentModel:  cfg.Agent.SubagentModel,
+		SubagentEffort: cfg.Agent.SubagentEffort,
+		AutoPlan:       desktopAutoPlanMode(cfg.Agent.AutoPlan),
+		Providers:      []ProviderView{},
 		Permissions: PermissionsView{
 			Mode:  orDefault(cfg.Permissions.Mode, "ask"),
 			Allow: nonNil(cfg.Permissions.Allow),
@@ -389,6 +393,45 @@ func (a *App) SetPlannerModel(ref string) error {
 	})
 }
 
+// SetSubagentModel sets (or clears) the default model used by subagent entry points.
+func (a *App) SetSubagentModel(ref string) error {
+	return a.applyConfigChange(func(c *config.Config) error {
+		ref = strings.TrimSpace(ref)
+		if ref != "" {
+			if _, ok := c.ResolveModel(ref); !ok {
+				return fmt.Errorf("unknown subagent model %q", ref)
+			}
+		}
+		c.Agent.SubagentModel = ref
+		return nil
+	})
+}
+
+// SetSubagentEffort sets (or clears) the default effort used by subagent entry points.
+func (a *App) SetSubagentEffort(level string) error {
+	return a.applyConfigChange(func(c *config.Config) error {
+		level = strings.TrimSpace(level)
+		if level == "" || level == "auto" {
+			c.Agent.SubagentEffort = ""
+			return nil
+		}
+		model := strings.TrimSpace(c.Agent.SubagentModel)
+		if model == "" {
+			model = c.DefaultModel
+		}
+		entry, ok := c.ResolveModel(model)
+		if !ok {
+			return fmt.Errorf("unknown subagent model %q", model)
+		}
+		effort, err := config.NormalizeEffort(entry, level)
+		if err != nil {
+			return err
+		}
+		c.Agent.SubagentEffort = effort
+		return nil
+	})
+}
+
 // SetAutoPlan updates the automatic plan-mode gate (off|on).
 func (a *App) SetAutoPlan(mode string) error {
 	return a.applyConfigChange(func(c *config.Config) error { return c.SetAutoPlan(mode) })
diff --git a/desktop/skills_app_test.go b/desktop/skills_app_test.go
index fa0aca78c..7c9b4e33e 100644
--- a/desktop/skills_app_test.go
+++ b/desktop/skills_app_test.go
@@ -24,17 +24,19 @@ func TestNormalizeSkillPathDirectoryLayout(t *testing.T) {
 	}
 }
 
-func TestSkillRootsViewCountsProjectSkills(t *testing.T) {
+func TestSkillRootsViewCountsGlobalSkills(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
 	t.Setenv("AppData", filepath.Join(home, "AppData"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData"))
 	project := t.TempDir()
-	root := filepath.Join(project, ".reasonix", "skills")
+	root := filepath.Join(home, ".reasonix", "skills")
 	if err := os.MkdirAll(root, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(root, "proj.md"), []byte("---\ndescription: project\n---\nbody"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(root, "global.md"), []byte("---\ndescription: global\n---\nbody"), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	wd, err := os.Getwd()
@@ -50,23 +52,25 @@ func TestSkillRootsViewCountsProjectSkills(t *testing.T) {
 	want := realTestPath(root)
 	for _, r := range roots {
 		if realTestPath(r.Dir) == want {
-			if r.Status != "ok" || r.Skills != 1 || r.Scope != "project" {
-				t.Fatalf("project root view = %+v", r)
+			if r.Status != "ok" || r.Skills != 1 || r.Scope != "global" {
+				t.Fatalf("global root view = %+v", r)
 			}
-			if len(r.SkillItems) != 1 || r.SkillItems[0].Name != "proj" || r.SkillItems[0].Description != "project" {
-				t.Fatalf("project root skill items = %+v", r.SkillItems)
+			if len(r.SkillItems) != 1 || r.SkillItems[0].Name != "global" || r.SkillItems[0].Description != "global" {
+				t.Fatalf("global root skill items = %+v", r.SkillItems)
 			}
 			return
 		}
 	}
-	t.Fatalf("project skill root %q not found in %+v", root, roots)
+	t.Fatalf("global skill root %q not found in %+v", root, roots)
 }
 
 func TestSkillRootsViewMarksEnvConfiguredCustomRoot(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
 	t.Setenv("AppData", filepath.Join(home, "AppData"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData"))
 	project := t.TempDir()
 	root := filepath.Join(home, "custom-skills")
 	if err := os.MkdirAll(root, 0o755); err != nil {
diff --git a/desktop/tab_profile_test.go b/desktop/tab_profile_test.go
index 499e55feb..91504a048 100644
--- a/desktop/tab_profile_test.go
+++ b/desktop/tab_profile_test.go
@@ -7,6 +7,7 @@ import (
 	"strings"
 	"testing"
 
+	"reasonix/internal/config"
 	"reasonix/internal/control"
 )
 
@@ -64,7 +65,7 @@ func TestSetEffortForTabIsTabLocal(t *testing.T) {
 	}
 }
 
-func TestEffortForTabResolvesProjectProviderConfig(t *testing.T) {
+func TestEffortForTabResolvesGlobalProviderConfig(t *testing.T) {
 	isolateDesktopUserDirs(t)
 
 	projectRoot := t.TempDir()
@@ -77,7 +78,10 @@ model = "deepseek-v4-flash"
 api_key_env = "PROJECT_API_KEY"
 effort = "max"
 `
-	if err := os.WriteFile(filepath.Join(projectRoot, "reasonix.toml"), []byte(configBody), 0o644); err != nil {
+	if err := os.MkdirAll(filepath.Dir(userConfigPathForTest()), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(userConfigPathForTest(), []byte(configBody), 0o644); err != nil {
 		t.Fatal(err)
 	}
 
@@ -90,7 +94,7 @@ effort = "max"
 
 	got := app.EffortForTab(tab.ID)
 	if !got.Supported || got.Current != "max" {
-		t.Fatalf("EffortForTab project config = %+v, want supported max", got)
+		t.Fatalf("EffortForTab global config = %+v, want supported max", got)
 	}
 }
 
@@ -152,8 +156,5 @@ func TestSaveTabsDoesNotPersistYoloMode(t *testing.T) {
 }
 
 func userConfigPathForTest() string {
-	if dir, err := os.UserConfigDir(); err == nil {
-		return dir + "/reasonix/reasonix.toml"
-	}
-	return ""
+	return config.UserConfigPath()
 }
diff --git a/desktop/wire.go b/desktop/wire.go
index 15c6ec73a..95db13670 100644
--- a/desktop/wire.go
+++ b/desktop/wire.go
@@ -55,15 +55,21 @@ type wireAsk struct {
 }
 
 type wireTool struct {
-	ID        string `json:"id,omitempty"`
-	Name      string `json:"name"`
-	Args      string `json:"args,omitempty"`
-	Output    string `json:"output,omitempty"`
-	Err       string `json:"err,omitempty"`
-	ReadOnly  bool   `json:"readOnly"`
-	Truncated bool   `json:"truncated,omitempty"`
-	Partial   bool   `json:"partial,omitempty"`
-	ParentID  string `json:"parentId,omitempty"`
+	ID        string       `json:"id,omitempty"`
+	Name      string       `json:"name"`
+	Args      string       `json:"args,omitempty"`
+	Output    string       `json:"output,omitempty"`
+	Err       string       `json:"err,omitempty"`
+	ReadOnly  bool         `json:"readOnly"`
+	Truncated bool         `json:"truncated,omitempty"`
+	Partial   bool         `json:"partial,omitempty"`
+	ParentID  string       `json:"parentId,omitempty"`
+	Profile   *wireProfile `json:"profile,omitempty"`
+}
+
+type wireProfile struct {
+	Model  string `json:"model,omitempty"`
+	Effort string `json:"effort,omitempty"`
 }
 
 type wireUsage struct {
@@ -147,12 +153,16 @@ func toWire(e event.Event) wireEvent {
 			w.Level = "info"
 		}
 	case event.ToolDispatch, event.ToolResult, event.ToolProgress:
-		w.Tool = &wireTool{
+		wt := &wireTool{
 			ID: e.Tool.ID, Name: e.Tool.Name, Args: e.Tool.Args,
 			Output: e.Tool.Output, Err: e.Tool.Err,
 			ReadOnly: e.Tool.ReadOnly, Truncated: e.Tool.Truncated,
 			Partial: e.Tool.Partial, ParentID: e.Tool.ParentID,
 		}
+		if e.Tool.Profile != nil {
+			wt.Profile = &wireProfile{Model: e.Tool.Profile.Model, Effort: e.Tool.Profile.Effort}
+		}
+		w.Tool = wt
 	case event.Usage:
 		if u := e.Usage; u != nil {
 			w.Usage = &wireUsage{
diff --git a/desktop/wire_test.go b/desktop/wire_test.go
index 07f9bc1ea..4ac2e8ef8 100644
--- a/desktop/wire_test.go
+++ b/desktop/wire_test.go
@@ -67,6 +67,17 @@ func TestToWireToolDispatch(t *testing.T) {
 	}
 }
 
+func TestToWireToolDispatchProfile(t *testing.T) {
+	e := event.Event{Kind: event.ToolDispatch, Tool: event.Tool{
+		ID: "1", Name: "task", Args: `{"prompt":"x"}`,
+		Profile: &event.Profile{Model: "deepseek-pro", Effort: "max"},
+	}}
+	w := toWire(e)
+	if w.Tool == nil || w.Tool.Profile == nil || w.Tool.Profile.Model != "deepseek-pro" || w.Tool.Profile.Effort != "max" {
+		t.Errorf("tool profile = %+v", w.Tool)
+	}
+}
+
 func TestToWireToolResult(t *testing.T) {
 	e := event.Event{Kind: event.ToolResult, Tool: event.Tool{ID: "1", Output: "ok", Truncated: true}}
 	w := toWire(e)
diff --git a/internal/agent/agent.go b/internal/agent/agent.go
index 95fe1e75f..273134cf1 100644
--- a/internal/agent/agent.go
+++ b/internal/agent/agent.go
@@ -657,6 +657,11 @@ func (a *Agent) executeBatch(ctx context.Context, calls []provider.ToolCall) []s
 			if ch, ok := tool.PreviewChange(t, json.RawMessage(c.Arguments)); ok {
 				ev.FileDiff = event.FileDiff{Diff: ch.Diff, Added: ch.Added, Removed: ch.Removed}
 			}
+			if pr, ok := t.(interface {
+				ResolveProfile(json.RawMessage) *event.Profile
+			}); ok {
+				ev.Profile = pr.ResolveProfile(json.RawMessage(c.Arguments))
+			}
 		}
 		a.sink.Emit(event.Event{Kind: event.ToolDispatch, Tool: ev})
 	}
diff --git a/internal/agent/task.go b/internal/agent/task.go
index 2072b0a70..82ee96844 100644
--- a/internal/agent/task.go
+++ b/internal/agent/task.go
@@ -24,6 +24,7 @@ var subagentMetaTools = []string{
 	"task",
 	"run_skill",
 	"install_skill",
+	"install_source",
 	"explore",
 	"research",
 	"review",
@@ -61,6 +62,9 @@ type TaskTool struct {
 	archiveDir        string
 	sysPrompt         string
 	gate              Gate
+	subagentModel     string
+	subagentEffort    string
+	resolveProvider   func(modelRef, effort string) (provider.Provider, *provider.Pricing, int, error)
 }
 
 // NewTaskTool wires a task tool to the parent agent's environment so its
@@ -70,7 +74,8 @@ type TaskTool struct {
 // deny rules still bite while autonomous sub-agents are never blocked on an
 // interactive prompt (there is no UI to answer one).
 func NewTaskTool(prov provider.Provider, pricing *provider.Pricing, parentReg *tool.Registry,
-	maxSteps, contextWindow int, softCompactRatio, compactRatio, compactForceRatio, temperature float64, archiveDir, sysPrompt string, gate Gate) *TaskTool {
+	maxSteps, contextWindow int, softCompactRatio, compactRatio, compactForceRatio, temperature float64, archiveDir, sysPrompt string, gate Gate,
+	subagentModel, subagentEffort string, resolveProvider func(string, string) (provider.Provider, *provider.Pricing, int, error)) *TaskTool {
 	if sysPrompt == "" {
 		sysPrompt = DefaultTaskSystemPrompt
 	}
@@ -87,6 +92,9 @@ func NewTaskTool(prov provider.Provider, pricing *provider.Pricing, parentReg *t
 		archiveDir:        archiveDir,
 		sysPrompt:         sysPrompt,
 		gate:              gate,
+		subagentModel:     subagentModel,
+		subagentEffort:    subagentEffort,
+		resolveProvider:   resolveProvider,
 	}
 }
 
@@ -104,7 +112,9 @@ func (t *TaskTool) Schema() json.RawMessage {
   "description":{"type":"string","description":"Short label for the sub-task (3-7 words). Surfaced in the dispatch line so the user sees what's running."},
   "tools":{"type":"array","items":{"type":"string"},"description":"Optional tool whitelist. Subagent/skill meta-tools are still excluded so delegation stays one layer deep."},
   "max_steps":{"type":"integer","description":"Optional cap on tool-call rounds. Defaults to half the parent's cap (min 5).","minimum":1},
-  "run_in_background":{"type":"boolean","description":"Run the sub-agent asynchronously: returns a job id immediately and keeps working across turns. Collect its final answer with wait, and you'll be notified when it finishes. Use for long, independent sub-tasks you don't need to block on right now."}
+  "run_in_background":{"type":"boolean","description":"Run the sub-agent asynchronously: returns a job id immediately and keeps working across turns. Collect its final answer with wait, and you'll be notified when it finishes. Use for long, independent sub-tasks you don't need to block on right now."},
+  "model":{"type":"string","description":"Optional model override for the sub-agent (a configured provider/model name)."},
+  "effort":{"type":"string","description":"Optional reasoning effort for the sub-agent (e.g. high, max)."}
 },
 "required":["prompt"]
 }`)
@@ -115,6 +125,34 @@ func (t *TaskTool) Schema() json.RawMessage {
 // running two sub-agents at once and letting their writes race.
 func (t *TaskTool) ReadOnly() bool { return false }
 
+// ResolveProfile extracts model/effort from task args and applies config defaults.
+func (t *TaskTool) ResolveProfile(args json.RawMessage) *event.Profile {
+	var p struct {
+		Model  string `json:"model"`
+		Effort string `json:"effort"`
+	}
+	if err := json.Unmarshal(args, &p); err != nil {
+		return nil
+	}
+	model, effort := t.effectiveProfile(p.Model, p.Effort)
+	if model == "" && effort == "" {
+		return nil
+	}
+	return &event.Profile{Model: model, Effort: effort}
+}
+
+func (t *TaskTool) effectiveProfile(model, effort string) (string, string) {
+	model = strings.TrimSpace(model)
+	effort = strings.TrimSpace(effort)
+	if model == "" {
+		model = strings.TrimSpace(t.subagentModel)
+	}
+	if effort == "" {
+		effort = strings.TrimSpace(t.subagentEffort)
+	}
+	return model, effort
+}
+
 func (t *TaskTool) Execute(ctx context.Context, args json.RawMessage) (string, error) {
 	var p struct {
 		Prompt          string   `json:"prompt"`
@@ -122,6 +160,8 @@ func (t *TaskTool) Execute(ctx context.Context, args json.RawMessage) (string, e
 		Tools           []string `json:"tools"`
 		MaxSteps        int      `json:"max_steps"`
 		RunInBackground bool     `json:"run_in_background"`
+		Model           string   `json:"model"`
+		Effort          string   `json:"effort"`
 	}
 	if err := json.Unmarshal(args, &p); err != nil {
 		return "", fmt.Errorf("invalid args: %w", err)
@@ -146,6 +186,7 @@ func (t *TaskTool) Execute(ctx context.Context, args json.RawMessage) (string, e
 	}
 
 	subReg := t.buildSubReg(p.Tools)
+	modelRef, effortRef := t.effectiveProfile(p.Model, p.Effort)
 
 	// Background: register a job that runs the sub-agent under the manager's
 	// session context (so it survives this turn) and return immediately. The
@@ -163,13 +204,13 @@ func (t *TaskTool) Execute(ctx context.Context, args json.RawMessage) (string, e
 			label = "task"
 		}
 		job := jm.Start("task", label, func(jobCtx context.Context, _ io.Writer) (string, error) {
-			return t.runSub(jobCtx, p.Prompt, subReg, nested, maxSteps)
+			return t.runSub(jobCtx, p.Prompt, subReg, nested, maxSteps, modelRef, effortRef)
 		})
 		return fmt.Sprintf("Started background task %q (%s). It runs across turns; collect its final answer with wait (or wait will return it once done), and you'll be notified when it finishes.", job.ID, label), nil
 	}
 
 	// Foreground: run synchronously, nesting events under this call.
-	return t.runSub(ctx, p.Prompt, subReg, subSink(ctx), maxSteps)
+	return t.runSub(ctx, p.Prompt, subReg, subSink(ctx), maxSteps, modelRef, effortRef)
 }
 
 // buildSubReg returns the sub-agent's tool set: the named whitelist (minus
@@ -206,14 +247,22 @@ func FilterRegistry(parent *tool.Registry, names []string, exclude ...string) *t
 
 // runSub builds a sub-agent over subReg, runs prompt to completion emitting to
 // sink, and returns its final assistant answer. Shared by the foreground and
-// background paths.
-func (t *TaskTool) runSub(ctx context.Context, prompt string, subReg *tool.Registry, sink event.Sink, maxSteps int) (string, error) {
-	return RunSubAgent(ctx, t.prov, subReg, t.sysPrompt, prompt, Options{
+// background paths. modelRef and effort override the parent defaults when non-empty.
+func (t *TaskTool) runSub(ctx context.Context, prompt string, subReg *tool.Registry, sink event.Sink, maxSteps int, modelRef, effort string) (string, error) {
+	prov, pricing, ctxWin := t.prov, t.pricing, t.contextWindow
+	if t.resolveProvider != nil && (modelRef != "" || effort != "") {
+		p, pr, cw, err := t.resolveProvider(modelRef, effort)
+		if err != nil {
+			return "", fmt.Errorf("sub-agent profile: %w", err)
+		}
+		prov, pricing, ctxWin = p, pr, cw
+	}
+	return RunSubAgent(ctx, prov, subReg, t.sysPrompt, prompt, Options{
 		MaxSteps:          maxSteps,
 		Temperature:       t.temperature,
-		Pricing:           t.pricing,
+		Pricing:           pricing,
 		Gate:              t.gate,
-		ContextWindow:     t.contextWindow,
+		ContextWindow:     ctxWin,
 		SoftCompactRatio:  t.softCompactRatio,
 		CompactRatio:      t.compactRatio,
 		CompactForceRatio: t.compactForceRatio,
diff --git a/internal/agent/task_test.go b/internal/agent/task_test.go
index c57855472..66696d65c 100644
--- a/internal/agent/task_test.go
+++ b/internal/agent/task_test.go
@@ -2,6 +2,7 @@ package agent
 
 import (
 	"context"
+	"errors"
 	"strings"
 	"testing"
 
@@ -18,7 +19,7 @@ func TestTaskToolReturnsSubAgentFinalAnswer(t *testing.T) {
 		{Type: provider.ChunkDone},
 	}}
 	parentReg := tool.NewRegistry()
-	task := NewTaskTool(sub, nil, parentReg, 20, 0, 0, 0, 0, 0.0, "", "test-sys-prompt", nil)
+	task := NewTaskTool(sub, nil, parentReg, 20, 0, 0, 0, 0, 0.0, "", "test-sys-prompt", nil, "", "", nil)
 
 	out, err := task.Execute(context.Background(), []byte(`{"prompt":"find callers of Foo"}`))
 	if err != nil {
@@ -51,7 +52,7 @@ func TestTaskToolFiltersTools(t *testing.T) {
 	parentReg.Add(fakeTool{name: "read_file", readOnly: true})
 	parentReg.Add(fakeTool{name: "write_file", readOnly: false})
 	parentReg.Add(fakeTool{name: "bash", readOnly: false})
-	task := NewTaskTool(sub, nil, parentReg, 20, 0, 0, 0, 0, 0.0, "", "sys", nil)
+	task := NewTaskTool(sub, nil, parentReg, 20, 0, 0, 0, 0, 0.0, "", "sys", nil, "", "", nil)
 	parentReg.Add(task) // simulate the wiring in cli.setup
 	parentReg.Add(fakeTool{name: "run_skill", readOnly: false})
 	parentReg.Add(fakeTool{name: "research", readOnly: false})
@@ -80,7 +81,7 @@ func TestTaskToolDefaultsToParentToolsWithoutMetaTools(t *testing.T) {
 	parentReg := tool.NewRegistry()
 	parentReg.Add(fakeTool{name: "read_file", readOnly: true})
 	parentReg.Add(fakeTool{name: "grep", readOnly: true})
-	task := NewTaskTool(sub, nil, parentReg, 20, 0, 0, 0, 0, 0.0, "", "sys", nil)
+	task := NewTaskTool(sub, nil, parentReg, 20, 0, 0, 0, 0, 0.0, "", "sys", nil, "", "", nil)
 	parentReg.Add(task)
 	parentReg.Add(fakeTool{name: "run_skill", readOnly: false})
 	parentReg.Add(fakeTool{name: "explore", readOnly: false})
@@ -101,3 +102,47 @@ func TestTaskToolDefaultsToParentToolsWithoutMetaTools(t *testing.T) {
 		t.Errorf("default sub-agent tools = %v, want normal tools inherited and meta-tools stripped", got)
 	}
 }
+
+func TestTaskToolUsesConfiguredProfileForExecution(t *testing.T) {
+	parent := &mockProvider{name: "parent", chunks: []provider.Chunk{
+		{Type: provider.ChunkText, Text: "parent answer"},
+		{Type: provider.ChunkDone},
+	}}
+	resolved := &mockProvider{name: "resolved", chunks: []provider.Chunk{
+		{Type: provider.ChunkText, Text: "resolved answer"},
+		{Type: provider.ChunkDone},
+	}}
+	var gotModel, gotEffort string
+	task := NewTaskTool(parent, nil, tool.NewRegistry(), 20, 0, 0, 0, 0, 0.0, "", "sys", nil, "deepseek-pro", "max",
+		func(model, effort string) (provider.Provider, *provider.Pricing, int, error) {
+			gotModel, gotEffort = model, effort
+			return resolved, nil, 0, nil
+		})
+
+	out, err := task.Execute(context.Background(), []byte(`{"prompt":"x"}`))
+	if err != nil {
+		t.Fatalf("Execute: %v", err)
+	}
+	if !strings.Contains(out, "resolved answer") {
+		t.Fatalf("sub-agent did not use resolved provider, got %q", out)
+	}
+	if gotModel != "deepseek-pro" || gotEffort != "max" {
+		t.Fatalf("resolved profile = %q/%q, want deepseek-pro/max", gotModel, gotEffort)
+	}
+}
+
+func TestTaskToolReturnsProfileResolutionErrors(t *testing.T) {
+	parent := &mockProvider{name: "parent", chunks: []provider.Chunk{
+		{Type: provider.ChunkText, Text: "parent answer"},
+		{Type: provider.ChunkDone},
+	}}
+	task := NewTaskTool(parent, nil, tool.NewRegistry(), 20, 0, 0, 0, 0, 0.0, "", "sys", nil, "", "",
+		func(string, string) (provider.Provider, *provider.Pricing, int, error) {
+			return nil, nil, 0, errors.New("bad effort")
+		})
+
+	_, err := task.Execute(context.Background(), []byte(`{"prompt":"x","effort":"turbo"}`))
+	if err == nil || !strings.Contains(err.Error(), "bad effort") {
+		t.Fatalf("Execute error = %v, want profile resolution error", err)
+	}
+}
diff --git a/internal/boot/boot.go b/internal/boot/boot.go
index f8bc9d3b2..47abe84bc 100644
--- a/internal/boot/boot.go
+++ b/internal/boot/boot.go
@@ -25,6 +25,7 @@ import (
 	"reasonix/internal/control"
 	"reasonix/internal/event"
 	"reasonix/internal/hook"
+	"reasonix/internal/installsource"
 	"reasonix/internal/instruction"
 	"reasonix/internal/jobs"
 	"reasonix/internal/lsp"
@@ -188,10 +189,11 @@ func Build(ctx context.Context, opts Options) (*control.Controller, error) {
 		ProjectRoot:   root,
 		CustomPaths:   cfg.SkillCustomPaths(),
 		DisabledNames: cfg.DisabledSkillNames(),
+		MaxDepth:      cfg.SkillMaxDepth(),
 		Stderr:        opts.Stderr,
 	})
 	skills := skillStore.List()
-	allSkills := skill.New(skill.Options{ProjectRoot: root, CustomPaths: cfg.SkillCustomPaths(), Stderr: io.Discard}).List()
+	allSkills := skill.New(skill.Options{ProjectRoot: root, CustomPaths: cfg.SkillCustomPaths(), MaxDepth: cfg.SkillMaxDepth(), Stderr: io.Discard}).List()
 	sysPrompt = skill.ApplyIndex(sysPrompt, skills)
 
 	reg := tool.NewRegistry()
@@ -209,8 +211,8 @@ func Build(ctx context.Context, opts Options) (*control.Controller, error) {
 	pluginHost := plugin.NewHost()
 
 	// Partition configured plugins by tier so eager/lazy/background can each
-	// take the path that fits them. User entries default to lazy — they don't
-	// slow the next launch unless the user explicitly opts in to eager.
+	// take the path that fits them. User entries default to background: the
+	// session starts immediately while enabled MCP servers warm up.
 	eagerEntries, lazyEntries, bgEntries := partitionByTier(cfg.AutoStartPlugins())
 
 	// Auto-demote: any eager plugin that has been chronically slow (recent
@@ -409,9 +411,37 @@ func Build(ctx context.Context, opts Options) (*control.Controller, error) {
 	// sub-agents inherit the full tool set (minus `task` itself, to keep
 	// nesting out of the picture). It registers into the same reg the
 	// executor uses, so the model surfaces it like any other tool.
+	resolveSubagentProvider := func(modelRef, effort string) (provider.Provider, *provider.Pricing, int, error) {
+		me := *entry
+		if strings.TrimSpace(modelRef) != "" {
+			resolved, ok := cfg.ResolveModel(modelRef)
+			if !ok {
+				return nil, nil, 0, fmt.Errorf("unknown model %q", modelRef)
+			}
+			me = *resolved
+		}
+		if strings.TrimSpace(effort) != "" {
+			normalized, err := config.NormalizeEffort(&me, effort)
+			if err != nil {
+				return nil, nil, 0, err
+			}
+			me.Effort = normalized
+			if me.Kind == "anthropic" && strings.TrimSpace(me.Effort) != "" && strings.TrimSpace(me.Thinking) == "" {
+				me.Thinking = "adaptive"
+			}
+		}
+		p, err := NewProviderWithProxy(&me, proxySpec)
+		if err != nil {
+			return nil, nil, 0, err
+		}
+		return p, me.Price, me.ContextWindow, nil
+	}
+	taskModel := firstNonEmpty(cfg.Agent.SubagentModels["task"], cfg.Agent.SubagentModel)
+	taskEffort := firstNonEmpty(cfg.Agent.SubagentEfforts["task"], cfg.Agent.SubagentEffort)
 	reg.Add(agent.NewTaskTool(execProv, entry.Price, reg, maxSteps,
 		entry.ContextWindow, cfg.Agent.SoftCompactRatio, cfg.Agent.CompactRatio, cfg.Agent.CompactForceRatio,
-		cfg.Agent.Temperature, config.ArchiveDir(), "", headlessGate))
+		cfg.Agent.Temperature, config.ArchiveDir(), "", headlessGate,
+		taskModel, taskEffort, resolveSubagentProvider))
 
 	// The `remember` tool lets the model persist durable facts to the project's
 	// auto-memory store; `forget` prunes ones that turn out wrong. The saved index
@@ -433,12 +463,14 @@ func Build(ctx context.Context, opts Options) (*control.Controller, error) {
 	// Its tool activity nests under the invoking call, like `task`.
 	skillRunner := func(sctx context.Context, sk skill.Skill, task string) (string, error) {
 		prov, price, ctxWin := execProv, entry.Price, entry.ContextWindow
-		if modelRef := subagentModelRef(cfg, sk); modelRef != "" {
-			if me, ok := cfg.ResolveModel(modelRef); ok {
-				if p, err := NewProviderWithProxy(me, proxySpec); err == nil {
-					prov, price, ctxWin = p, me.Price, me.ContextWindow
-				}
+		modelRef := subagentModelRef(cfg, sk)
+		effortRef := subagentEffortRef(cfg, sk)
+		if modelRef != "" || effortRef != "" {
+			p, pr, cw, err := resolveSubagentProvider(modelRef, effortRef)
+			if err != nil {
+				return "", fmt.Errorf("subagent skill %q profile: %w", sk.Name, err)
 			}
+			prov, price, ctxWin = p, pr, cw
 		}
 		subReg := agent.FilterRegistry(reg, sk.AllowedTools, agent.SubagentMetaTools()...)
 		steps := maxSteps
@@ -456,9 +488,61 @@ func Build(ctx context.Context, opts Options) (*control.Controller, error) {
 			ArchiveDir:    config.ArchiveDir(),
 		}, agent.NestedSink(sctx, event.Discard))
 	}
-	reg.Add(skill.NewRunSkillTool(skillStore, skillRunner))
+	skillProfile := func(sk skill.Skill) *event.Profile {
+		model, effort := subagentModelRef(cfg, sk), subagentEffortRef(cfg, sk)
+		if model == "" && effort == "" {
+			return nil
+		}
+		return &event.Profile{Model: model, Effort: effort}
+	}
+	reg.Add(skill.NewRunSkillTool(skillStore, skillRunner, skillProfile))
 	reg.Add(skill.NewInstallSkillTool(skillStore, nil))
-	for _, t := range skill.BuiltinSubagentTools(skillStore, skillRunner) {
+	reg.Add(installsource.NewTool(installsource.Options{
+		ProjectRoot: root,
+		HTTPClient:  balanceClient,
+		ConnectMCP: func(e config.PluginEntry) (installsource.MCPConnectResult, error) {
+			exp := e.ExpandedPlugin()
+			spec := plugin.Spec{
+				Name:    exp.Name,
+				Type:    exp.Type,
+				Command: exp.Command,
+				Args:    exp.Args,
+				Env:     exp.Env,
+				URL:     exp.URL,
+				Headers: exp.Headers,
+			}
+			if opts.Stderr != nil {
+				spec.Stderr = opts.Stderr
+			}
+			tools, err := pluginHost.Add(ctx, spec)
+			if err != nil {
+				return installsource.MCPConnectResult{}, err
+			}
+			reg.RemovePrefix(plugin.ToolPrefix(spec.Name))
+			for _, t := range tools {
+				reg.Add(t)
+			}
+			// Disconnect closes the server and drops its namespaced tools.
+			// Used by the install_source rollback path when SaveTo fails.
+			disconnect := func() {
+				if prefix, ok := pluginHost.Remove(spec.Name); ok {
+					reg.RemovePrefix(prefix)
+				}
+			}
+			return installsource.MCPConnectResult{
+				ToolCount:  len(tools),
+				Disconnect: disconnect,
+			}, nil
+		},
+		OnDisconnect: func(serverName string) bool {
+			if prefix, ok := pluginHost.Remove(serverName); ok {
+				reg.RemovePrefix(prefix)
+				return true
+			}
+			return false
+		},
+	}))
+	for _, t := range skill.BuiltinSubagentTools(skillStore, skillRunner, skillProfile) {
 		reg.Add(t)
 	}
 
@@ -586,17 +670,22 @@ func rememberPermissionRule(workspaceRoot, rule string) {
 }
 
 func rememberPermissionConfigPath(workspaceRoot string) string {
-	workspaceRoot = strings.TrimSpace(workspaceRoot)
-	if workspaceRoot != "" {
-		return filepath.Join(workspaceRoot, "reasonix.toml")
-	}
-	path := config.SourcePath()
+	path := config.UserConfigPath()
 	if path == "" {
-		path = "reasonix.toml" // match Config.Save() fallback
+		path = "reasonix.toml"
 	}
 	return path
 }
 
+func firstNonEmpty(vals ...string) string {
+	for _, v := range vals {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
 func subagentModelRef(cfg *config.Config, sk skill.Skill) string {
 	if cfg != nil {
 		for _, key := range subagentModelKeys(sk.Name) {
@@ -614,6 +703,23 @@ func subagentModelRef(cfg *config.Config, sk skill.Skill) string {
 	return strings.TrimSpace(cfg.Agent.SubagentModel)
 }
 
+func subagentEffortRef(cfg *config.Config, sk skill.Skill) string {
+	if cfg != nil {
+		for _, key := range subagentModelKeys(sk.Name) {
+			if e := strings.TrimSpace(cfg.Agent.SubagentEfforts[key]); e != "" {
+				return e
+			}
+		}
+	}
+	if e := strings.TrimSpace(sk.Effort); e != "" {
+		return e
+	}
+	if cfg == nil {
+		return ""
+	}
+	return strings.TrimSpace(cfg.Agent.SubagentEffort)
+}
+
 func subagentModelKeys(name string) []string {
 	name = strings.TrimSpace(name)
 	if name == "" {
@@ -713,7 +819,8 @@ func addBuiltins(reg *tool.Registry, enabled, writeRoots []string, bashSpec sand
 // partitionByTier splits configured plugin entries into the three startup
 // buckets — eager (block boot until ready), lazy (placeholder until first
 // model use), background (placeholder + start spawn now). Entries with an
-// unrecognised or empty tier land in lazy (the default).
+// empty tier land in background; unrecognised non-empty tiers land in lazy so a
+// typo never triggers unexpected background work.
 func partitionByTier(entries []config.PluginEntry) (eager, lazy, bg []config.PluginEntry) {
 	for _, e := range entries {
 		switch e.ResolvedTier() {
diff --git a/internal/boot/boot_test.go b/internal/boot/boot_test.go
index a5a2a5697..eebedaa64 100644
--- a/internal/boot/boot_test.go
+++ b/internal/boot/boot_test.go
@@ -34,10 +34,13 @@ import (
 // into the session's system message (the cached prefix), and the `remember`
 // tool is registered. It builds a real Controller from a throwaway project dir.
 func TestBuildFoldsProjectMemoryIntoSystemPrompt(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	dir := t.TempDir()
 	t.Chdir(dir)
 
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -59,7 +62,7 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	// The system message is the cached prefix; it must contain both the base
 	// prompt and the discovered memory.
@@ -125,9 +128,12 @@ func TestBuildDiscoversSkills(t *testing.T) {
 	dir := t.TempDir()
 	home := t.TempDir()
 	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+	t.Setenv("AppData", filepath.Join(home, "AppData"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData"))
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -143,13 +149,13 @@ base_url = "https://example.invalid"
 model = "x"
 api_key_env = "REASONIX_TEST_KEY_UNSET"
 `)
-	writeFile(t, dir, ".reasonix/skills/projskill.md", "---\ndescription: a project skill\n---\nplaybook")
+	writeFile(t, home, ".reasonix/skills/projskill.md", "---\ndescription: a project skill\n---\nplaybook")
 
 	ctrl, err := Build(context.Background(), Options{})
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	var hasProj, hasBuiltin bool
 	for _, s := range ctrl.Skills() {
@@ -195,9 +201,12 @@ func TestBuildOmitsDisabledSkillsFromPromptAndRuntimeList(t *testing.T) {
 	dir := t.TempDir()
 	home := t.TempDir()
 	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+	t.Setenv("AppData", filepath.Join(home, "AppData"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData"))
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -216,13 +225,13 @@ base_url = "https://example.invalid"
 model = "x"
 api_key_env = "REASONIX_TEST_KEY_UNSET"
 `)
-	writeFile(t, dir, ".reasonix/skills/projskill.md", "---\ndescription: a project skill\n---\nplaybook")
+	writeFile(t, home, ".reasonix/skills/projskill.md", "---\ndescription: a project skill\n---\nplaybook")
 
 	ctrl, err := Build(context.Background(), Options{})
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	for _, s := range ctrl.Skills() {
 		if s.Name == "projskill" || s.Name == "review" {
@@ -244,10 +253,11 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 	}
 }
 
-func TestBuildRecordsMCPStartupFailure(t *testing.T) {
+func TestBuildMigratesLegacyMCPStartupTier(t *testing.T) {
+	homeDir := isolateConfigHome(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(homeDir, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -268,31 +278,19 @@ name = "missing"
 command = "reasonix-missing-mcp-binary"
 tier = "eager"
 `)
-	var notices []event.Event
 	ctrl, err := Build(context.Background(), Options{
-		Sink: event.FuncSink(func(e event.Event) {
-			if e.Kind == event.Notice {
-				notices = append(notices, e)
-			}
-		}),
+		Sink: event.FuncSink(func(event.Event) {}),
 	})
 	if err != nil {
 		t.Fatalf("Build should not fail when an MCP server is unavailable: %v", err)
 	}
-	defer ctrl.Close()
-	failures := ctrl.Host().Failures()
-	if len(failures) != 1 || failures[0].Name != "missing" {
-		t.Fatalf("failures = %+v, want missing", failures)
-	}
-	foundNotice := false
-	for _, n := range notices {
-		if strings.Contains(n.Text, "failed to start") {
-			foundNotice = true
-			break
-		}
+	defer closeControllerForTest(ctrl)
+	raw, err := os.ReadFile(filepath.Join(homeDir, ".reasonix", "config.toml"))
+	if err != nil {
+		t.Fatal(err)
 	}
-	if !foundNotice {
-		t.Fatalf("missing startup warning notice: %+v", notices)
+	if strings.Contains(string(raw), "\ntier") {
+		t.Fatalf("legacy MCP tier should be removed during load:\n%s", raw)
 	}
 }
 
@@ -300,9 +298,12 @@ tier = "eager"
 // memory files, the system prompt is exactly the configured base — the cache
 // prefix is untouched by the memory feature.
 func TestBuildWithoutMemoryLeavesPromptUnchanged(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -323,7 +324,7 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	sys := systemMessage(ctrl.History())
 	// The built-in skills always append a "# Skills" index to the prefix; this
@@ -344,9 +345,12 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 }
 
 func TestBuildLanguagePolicyIsAppended(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -367,7 +371,7 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	sys := systemMessage(ctrl.History())
 	if !strings.Contains(sys, config.LanguagePolicy) {
@@ -423,13 +427,14 @@ allow = ["bash(workspace*)"]
 	const rule = "bash=go test ./..."
 	rememberPermissionRule(workspace, rule)
 
+	// Rule is written to global config regardless of workspace root
+	userCfg := config.LoadForEdit(config.UserConfigPath())
+	if !hasPermissionRule(userCfg.Permissions.Allow, rule) {
+		t.Fatalf("remembered rule missing from global config: %v", userCfg.Permissions.Allow)
+	}
 	cwdCfg := config.LoadForEdit(filepath.Join(cwd, "reasonix.toml"))
 	if hasPermissionRule(cwdCfg.Permissions.Allow, rule) {
-		t.Fatalf("remembered rule was written to cwd config: %v", cwdCfg.Permissions.Allow)
-	}
-	workspaceCfg := config.LoadForEdit(filepath.Join(workspace, "reasonix.toml"))
-	if !hasPermissionRule(workspaceCfg.Permissions.Allow, rule) {
-		t.Fatalf("remembered rule missing from workspace config: %v", workspaceCfg.Permissions.Allow)
+		t.Fatalf("rule should not be in cwd config: %v", cwdCfg.Permissions.Allow)
 	}
 }
 
@@ -478,15 +483,14 @@ func TestBuildMigratesLegacyConfigEndToEnd(t *testing.T) {
 	t.Setenv("USERPROFILE", home)                               // os.UserHomeDir on Windows
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config")) // os.UserConfigDir on Linux
 	t.Setenv("AppData", filepath.Join(home, "AppData"))         // os.UserConfigDir on Windows
-	t.Setenv("DEEPSEEK_API_KEY", "")                            // track for cleanup; migration os.Setenv's it live
+	t.Setenv("APPDATA", filepath.Join(home, "AppData"))
+	t.Setenv("DEEPSEEK_API_KEY", "") // track for cleanup; migration os.Setenv's it live
+	t.Setenv("PATH", t.TempDir())    // avoid resolving a real codegraph on the runner
 
 	proj := t.TempDir()
 	t.Chdir(proj)
-	// codegraph off keeps Build offline; it merges over the migrated user config
-	// without dropping the migrated plugins.
-	writeFile(t, proj, "reasonix.toml", "[codegraph]\nenabled = false\n")
 	writeFile(t, filepath.Join(home, ".reasonix"), "config.json",
-		`{"apiKey":"sk-e2e","lang":"zh","mcpServers":{"fs":{"command":"npx","args":["-y","server-fs"]}}}`)
+		`{"apiKey":"sk-e2e","lang":"zh","mcpServers":{"fs":{"command":"npx","args":["-y","server-fs"],"disabled":true}}}`)
 	writeFile(t, filepath.Join(home, ".reasonix", "sessions"), "chat-1.events.jsonl",
 		`{"type":"user.message","id":1,"ts":"t","turn":0,"text":"hello from v0.x"}`+"\n"+
 			`{"type":"model.final","id":2,"ts":"t","turn":0,"content":"hi","toolCalls":[],"usage":{},"costUsd":0}`+"\n")
@@ -502,7 +506,7 @@ func TestBuildMigratesLegacyConfigEndToEnd(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	migrated := false
 	for _, n := range notices {
@@ -519,8 +523,16 @@ func TestBuildMigratesLegacyConfigEndToEnd(t *testing.T) {
 	if err != nil {
 		t.Fatalf("v2 config not written to %s: %v", dest, err)
 	}
-	if !strings.Contains(string(data), `name    = "fs"`) || !strings.Contains(string(data), `language      = "zh"`) {
-		t.Errorf("migrated config missing plugin/lang:\n%s", data)
+	if !strings.Contains(string(data), `language      = "zh"`) {
+		t.Errorf("migrated config missing lang:\n%s", data)
+	}
+	// Plugins are now in mcp.toml
+	mcpData, err := os.ReadFile(config.UserMCPConfigPath())
+	if err != nil {
+		t.Fatalf("mcp.toml not written: %v", err)
+	}
+	if !strings.Contains(string(mcpData), `name    = "fs"`) {
+		t.Errorf("migrated mcp.toml missing plugin:\n%s", mcpData)
 	}
 
 	if got := os.Getenv("DEEPSEEK_API_KEY"); got != "sk-e2e" {
@@ -559,22 +571,25 @@ func isolateConfigHome(t *testing.T) string {
 	t.Helper()
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
+	t.Setenv("USERPROFILE", dir)
 	t.Setenv("XDG_CONFIG_HOME", dir)
+	t.Setenv("APPDATA", filepath.Join(dir, "AppData"))
+	t.Setenv("AppData", filepath.Join(dir, "AppData"))
 	return dir
 }
 
 // TestPartitionByTier pins the bucket assignment contract that the rest of
 // boot.go's plugin orchestration depends on: each tier string maps to its own
 // slice, the original order inside a tier is preserved (so /mcp status and
-// stats land deterministically), and a missing/unknown tier value falls into
-// lazy — the project default that keeps adding a plugin from ever slowing the
-// next launch.
+// stats land deterministically), an empty/missing tier defaults to background
+// (connects after session start without blocking chat), and unknown non-empty
+// values fall back to lazy so a typo never forces unwanted background connects.
 func TestPartitionByTier(t *testing.T) {
 	entries := []config.PluginEntry{
 		{Name: "e1", Tier: "eager"},
 		{Name: "l1", Tier: "lazy"},
 		{Name: "b1", Tier: "background"},
-		{Name: "default", Tier: ""}, // empty must default to lazy
+		{Name: "default", Tier: ""}, // empty defaults to background
 	}
 
 	eager, lazy, bg := partitionByTier(entries)
@@ -582,28 +597,20 @@ func TestPartitionByTier(t *testing.T) {
 	if len(eager) != 1 || eager[0].Name != "e1" {
 		t.Fatalf("eager bucket = %+v, want [e1]", eager)
 	}
-	if len(bg) != 1 || bg[0].Name != "b1" {
-		t.Fatalf("background bucket = %+v, want [b1]", bg)
+	if len(bg) != 2 || bg[0].Name != "b1" || bg[1].Name != "default" {
+		t.Fatalf("background bucket = %+v, want [b1, default] preserving input order", bg)
 	}
-	// Lazy holds both the explicit lazy entry and the default-fallback one, in
-	// the order they appeared in the input — proves the empty-tier default
-	// flows through partition without reshuffling.
-	if len(lazy) != 2 || lazy[0].Name != "l1" || lazy[1].Name != "default" {
-		t.Fatalf("lazy bucket = %+v, want [l1, default] preserving input order", lazy)
+	if len(lazy) != 1 || lazy[0].Name != "l1" {
+		t.Fatalf("lazy bucket = %+v, want [l1]", lazy)
 	}
 }
 
-// TestBuildEagerStartsAtBoot proves an eager-tier plugin actually completes
-// its handshake on the boot critical path: Host.ServerNames() must include the
-// plugin after Build returns. We point the plugin at this test binary running
-// as a stdio MCP helper (see TestHelperProcess), so the spawn is real but
-// deterministic and hermetic — no external MCP server required on PATH.
-func TestBuildEagerStartsAtBoot(t *testing.T) {
-	isolateConfigHome(t)
+func TestBuildMigratesLegacyEagerTierToBackground(t *testing.T) {
+	homeDir := isolateConfigHome(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
 
-	writeFile(t, dir, "reasonix.toml", fmt.Sprintf(`
+	writeFile(t, filepath.Join(homeDir, ".reasonix"), "config.toml", fmt.Sprintf(`
 default_model = "test-model"
 
 [codegraph]
@@ -633,39 +640,22 @@ env = { GO_WANT_HELPER_PROCESS = "1" }
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
-	names := ctrl.Host().ServerNames()
-	found := false
-	for _, n := range names {
-		if n == "eagermock" {
-			found = true
-			break
-		}
-	}
-	if !found {
-		t.Fatalf("eager plugin missing from Host.ServerNames() = %v — boot did not block on its handshake", names)
+	if !waitForMCPServerName(ctrl.Host(), "eagermock", 2*time.Second) {
+		t.Fatalf("legacy eager plugin did not connect in the background; names = %v", ctrl.Host().ServerNames())
 	}
 	if got := ctrl.Host().Failures(); len(got) != 0 {
-		t.Fatalf("Host.Failures() = %+v, want empty for a healthy eager plugin", got)
+		t.Fatalf("Host.Failures() = %+v, want empty for a healthy migrated plugin", got)
 	}
 }
 
-// TestBuildLazyDoesNotConnectAtBoot is the inverse of the eager test: a
-// lazy-tier plugin must NOT trigger a subprocess handshake during Build, so
-// the boot critical path stays empty even with a slow-to-spawn server in
-// config. We assert through Host.ServerNames() (must not list the plugin) and
-// Host.Failures() (lazy plugins never appear here — a failure surfaces only on
-// first model use, not at boot). The placeholder tool registration itself is
-// covered by internal/plugin/lazy_test.go's TestLazy* suite; the Registry has
-// no public accessor on Controller, so at this layer we pin the load-bearing
-// boot-time invariant — no spawn — rather than re-validating the placeholder.
-func TestBuildLazyDoesNotConnectAtBoot(t *testing.T) {
-	isolateConfigHome(t)
+func TestBuildMigratesLegacyLazyTierToBackground(t *testing.T) {
+	homeDir := isolateConfigHome(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
 
-	writeFile(t, dir, "reasonix.toml", fmt.Sprintf(`
+	writeFile(t, filepath.Join(homeDir, ".reasonix"), "config.toml", fmt.Sprintf(`
 default_model = "test-model"
 
 [codegraph]
@@ -695,41 +685,24 @@ env = { GO_WANT_HELPER_PROCESS = "1" }
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
-	for _, n := range ctrl.Host().ServerNames() {
-		if n == "lazymock" {
-			t.Fatalf("lazy plugin %q appeared in Host.ServerNames() — boot connected it eagerly", n)
-		}
+	if !waitForMCPServerName(ctrl.Host(), "lazymock", 2*time.Second) {
+		t.Fatalf("legacy lazy plugin did not connect in the background; names = %v", ctrl.Host().ServerNames())
 	}
 	if got := ctrl.Host().Failures(); len(got) != 0 {
-		t.Fatalf("Host.Failures() = %+v, want empty — lazy plugins must not even attempt a boot-time spawn", got)
-	}
-	// The configured plugin is still recognised as a configured-but-disconnected
-	// server, the same signal /mcp uses to render its "lazy, will connect on
-	// first use" line — proves the entry made it through partition into the
-	// lazy bucket rather than being dropped.
-	dconn := ctrl.DisconnectedMCPNames()
-	foundDisconnected := false
-	for _, n := range dconn {
-		if n == "lazymock" {
-			foundDisconnected = true
-			break
-		}
-	}
-	if !foundDisconnected {
-		t.Fatalf("DisconnectedMCPNames() = %v, want it to include the lazy plugin (configured but not connected)", dconn)
+		t.Fatalf("Host.Failures() = %+v, want empty for a healthy migrated plugin", got)
 	}
 }
 
 func TestBuildColdCodegraphStartsInBackground(t *testing.T) {
-	isolateConfigHome(t)
+	homeDir := isolateConfigHome(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
 	launcher := writeCodegraphHelper(t, dir)
 	t.Setenv("GO_WANT_HELPER_PROCESS", "1")
 
-	writeFile(t, dir, "reasonix.toml", fmt.Sprintf(`
+	writeFile(t, filepath.Join(homeDir, ".reasonix"), "config.toml", fmt.Sprintf(`
 default_model = "test-model"
 
 [codegraph]
@@ -761,7 +734,7 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
 	if got := ctrl.Host().Failures(); len(got) != 0 {
 		t.Fatalf("Host.Failures() = %+v, want empty for cold built-in codegraph background startup", got)
@@ -788,17 +761,8 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 	}
 }
 
-// TestBuildAutoDemoteFromStats proves the Phase 5 telemetry → Phase 4 tier
-// bridge: three consecutive over-budget startup samples must demote an
-// eager-tier plugin to lazy at the *next* boot, so the user pays for a slow
-// MCP server at most a handful of starts. We pre-seed three 30s samples for
-// "slowserver" (well above 2 * DefaultStartupBudget = 10s) via the public
-// RecordStartup API, then Build a config that declares "slowserver" eager and
-// verify (a) boot did NOT block on its handshake — the plugin is absent from
-// Host.ServerNames() — and (b) a Notice carrying the demote reason fired so
-// the user understands why their explicit "eager" was ignored this session.
-func TestBuildAutoDemoteFromStats(t *testing.T) {
-	isolateConfigHome(t)
+func TestBuildMigratesLegacyEagerBeforeStatsDemotion(t *testing.T) {
+	homeDir := isolateConfigHome(t)
 	dir := t.TempDir()
 	t.Chdir(dir)
 
@@ -811,7 +775,7 @@ func TestBuildAutoDemoteFromStats(t *testing.T) {
 		}
 	}
 
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(homeDir, ".reasonix"), "config.toml", `
 default_model = "test-model"
 
 [codegraph]
@@ -846,19 +810,11 @@ tier = "eager"
 	if err != nil {
 		t.Fatalf("Build: %v", err)
 	}
-	defer ctrl.Close()
+	defer closeControllerForTest(ctrl)
 
-	for _, n := range ctrl.Host().ServerNames() {
-		if n == "slowserver" {
-			t.Fatalf("demoted plugin %q still appeared in Host.ServerNames() — auto-demote did not move it out of the eager bucket", n)
-		}
-	}
-	// Crucially the missing-binary command never ran: a real eager attempt
-	// would have surfaced as a Failure with a spawn error. An empty failures
-	// list proves boot skipped the spawn entirely, not that it tried and
-	// silently swallowed the error.
-	if got := ctrl.Host().Failures(); len(got) != 0 {
-		t.Fatalf("Host.Failures() = %+v, want empty — demoted plugin should never have been spawned", got)
+	failures := waitForMCPFailure(t, ctrl.Host(), "slowserver", 2*time.Second)
+	if len(failures) != 1 || failures[0].Name != "slowserver" {
+		t.Fatalf("Host.Failures() = %+v, want background startup failure for migrated plugin", failures)
 	}
 
 	foundDemoteNotice := false
@@ -868,8 +824,47 @@ tier = "eager"
 			break
 		}
 	}
-	if !foundDemoteNotice {
-		t.Fatalf("no demote notice surfaced; got %+v", notices)
+	if foundDemoteNotice {
+		t.Fatalf("legacy tier should be migrated before demotion logic; got notices %+v", notices)
+	}
+}
+
+func waitForMCPServerName(h *plugin.Host, name string, timeout time.Duration) bool {
+	deadline := time.Now().Add(timeout)
+	for {
+		for _, n := range h.ServerNames() {
+			if n == name {
+				return true
+			}
+		}
+		if time.Now().After(deadline) {
+			return false
+		}
+		time.Sleep(10 * time.Millisecond)
+	}
+}
+
+func closeControllerForTest(ctrl interface{ Close() }) {
+	ctrl.Close()
+	if runtime.GOOS == "windows" {
+		time.Sleep(100 * time.Millisecond)
+	}
+}
+
+func waitForMCPFailure(t *testing.T, h *plugin.Host, name string, timeout time.Duration) []plugin.Failure {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	for {
+		failures := h.Failures()
+		for _, f := range failures {
+			if f.Name == name {
+				return failures
+			}
+		}
+		if time.Now().After(deadline) {
+			return failures
+		}
+		time.Sleep(10 * time.Millisecond)
 	}
 }
 
@@ -937,7 +932,10 @@ func TestHelperProcess(t *testing.T) {
 
 func writeCodegraphHelper(t *testing.T, dir string) string {
 	t.Helper()
-	path := filepath.Join(dir, "codegraph-helper")
+	path, err := filepath.Abs(filepath.Join(dir, "codegraph-helper"))
+	if err != nil {
+		t.Fatal(err)
+	}
 	if runtime.GOOS == "windows" {
 		path += ".exe"
 	}
diff --git a/internal/boot/model_error_test.go b/internal/boot/model_error_test.go
index 83a192f2f..c16b0c117 100644
--- a/internal/boot/model_error_test.go
+++ b/internal/boot/model_error_test.go
@@ -2,6 +2,7 @@ package boot
 
 import (
 	"context"
+	"path/filepath"
 	"strings"
 	"testing"
 
@@ -16,9 +17,12 @@ import (
 // fail with a message that names the model, lists what IS configured, and hints
 // at the [[providers]] trap — not a silent empty model.
 func TestBuildUnknownModelErrorIsActionable(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "mimo"
 
 [codegraph]
@@ -49,9 +53,12 @@ api_key_env = "REASONIX_TEST_KEY_UNSET"
 // notice naming the env var, instead of silently showing a dead/empty model.
 func TestBuildNoticesMissingAPIKey(t *testing.T) {
 	const keyEnv = "REASONIX_MISSING_KEY_FOR_TEST"
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	writeFile(t, dir, "reasonix.toml", `
+	writeFile(t, filepath.Join(home, ".reasonix"), "config.toml", `
 default_model = "x"
 
 [codegraph]
diff --git a/internal/boot/subagent_model_test.go b/internal/boot/subagent_model_test.go
index 863836f3f..b2f9f8d65 100644
--- a/internal/boot/subagent_model_test.go
+++ b/internal/boot/subagent_model_test.go
@@ -50,3 +50,42 @@ func TestSubagentModelRefAcceptsToolNameAliases(t *testing.T) {
 		t.Fatalf("security_review alias should configure security-review, got %q", got)
 	}
 }
+
+func TestSubagentEffortRefHonorsPrecedence(t *testing.T) {
+	cfg := config.Default()
+	cfg.Agent.SubagentEffort = "high"
+	cfg.Agent.SubagentEfforts = map[string]string{"review": "max"}
+
+	got := subagentEffortRef(cfg, skill.Skill{
+		Name:   "review",
+		RunAs:  skill.RunSubagent,
+		Effort: "low",
+	})
+	if got != "max" {
+		t.Fatalf("per-skill effort config should override skill frontmatter and default, got %q", got)
+	}
+
+	got = subagentEffortRef(cfg, skill.Skill{
+		Name:   "custom",
+		RunAs:  skill.RunSubagent,
+		Effort: "medium",
+	})
+	if got != "medium" {
+		t.Fatalf("skill frontmatter effort should override default config, got %q", got)
+	}
+
+	got = subagentEffortRef(cfg, skill.Skill{Name: "other", RunAs: skill.RunSubagent})
+	if got != "high" {
+		t.Fatalf("default subagent effort = %q, want high", got)
+	}
+}
+
+func TestSubagentEffortRefAcceptsToolNameAliases(t *testing.T) {
+	cfg := config.Default()
+	cfg.Agent.SubagentEfforts = map[string]string{"security_review": "max"}
+
+	got := subagentEffortRef(cfg, skill.Skill{Name: "security-review", RunAs: skill.RunSubagent})
+	if got != "max" {
+		t.Fatalf("security_review alias should configure security-review effort, got %q", got)
+	}
+}
diff --git a/internal/cli/acp.go b/internal/cli/acp.go
index 717cfe0a8..25efa920f 100644
--- a/internal/cli/acp.go
+++ b/internal/cli/acp.go
@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"os"
 	"os/signal"
+	"strings"
 
 	"reasonix/internal/acp"
 	"reasonix/internal/agent"
@@ -15,8 +16,10 @@ import (
 	"reasonix/internal/control"
 	"reasonix/internal/event"
 	"reasonix/internal/i18n"
+	"reasonix/internal/netclient"
 	"reasonix/internal/permission"
 	"reasonix/internal/plugin"
+	"reasonix/internal/provider"
 	"reasonix/internal/sandbox"
 	"reasonix/internal/tool"
 	"reasonix/internal/tool/builtin"
@@ -135,9 +138,12 @@ func (f *acpFactory) NewSession(ctx context.Context, p acp.SessionParams) (*cont
 	maxSteps := cfg.Agent.MaxSteps
 	policy := permission.New(cfg.Permissions.Mode, cfg.Permissions.Allow, cfg.Permissions.Ask, cfg.Permissions.Deny)
 	headlessGate := permission.NewGate(policy, nil)
+	taskModel, taskEffort := acpTaskProfileDefaults(cfg)
+	resolveSubagentProvider := newACPSubagentProviderResolver(cfg, entry, proxySpec)
 	reg.Add(agent.NewTaskTool(execProv, entry.Price, reg, maxSteps,
 		entry.ContextWindow, cfg.Agent.SoftCompactRatio, cfg.Agent.CompactRatio, cfg.Agent.CompactForceRatio,
-		cfg.Agent.Temperature, config.ArchiveDir(), "", headlessGate))
+		cfg.Agent.Temperature, config.ArchiveDir(), "", headlessGate,
+		taskModel, taskEffort, resolveSubagentProvider))
 
 	executor := agent.New(execProv, reg, agent.NewSession(sysPrompt), agent.Options{
 		MaxSteps:          maxSteps,
@@ -197,3 +203,54 @@ func acpBuiltinTools(cfg *config.Config, cwd string, writeRoots []string) []tool
 	}
 	return ws.Tools(cfg.Tools.Enabled...)
 }
+
+func acpTaskProfileDefaults(cfg *config.Config) (string, string) {
+	if cfg == nil {
+		return "", ""
+	}
+	model := strings.TrimSpace(cfg.Agent.SubagentModels["task"])
+	if model == "" {
+		model = strings.TrimSpace(cfg.Agent.SubagentModel)
+	}
+	effort := strings.TrimSpace(cfg.Agent.SubagentEfforts["task"])
+	if effort == "" {
+		effort = strings.TrimSpace(cfg.Agent.SubagentEffort)
+	}
+	return model, effort
+}
+
+func newACPSubagentProviderResolver(cfg *config.Config, parent *config.ProviderEntry, proxySpec netclient.ProxySpec) func(string, string) (provider.Provider, *provider.Pricing, int, error) {
+	return func(modelRef, effort string) (provider.Provider, *provider.Pricing, int, error) {
+		modelRef = strings.TrimSpace(modelRef)
+		effort = strings.TrimSpace(effort)
+
+		var entry *config.ProviderEntry
+		if modelRef != "" {
+			var ok bool
+			entry, ok = cfg.ResolveModel(modelRef)
+			if !ok {
+				return nil, nil, 0, fmt.Errorf("subagent_model %q is not a configured provider", modelRef)
+			}
+		} else {
+			cp := *parent
+			entry = &cp
+		}
+
+		if effort != "" {
+			normalized, err := config.NormalizeEffort(entry, effort)
+			if err != nil {
+				return nil, nil, 0, err
+			}
+			entry.Effort = normalized
+			if entry.Kind == "anthropic" && strings.TrimSpace(entry.Effort) != "" && strings.TrimSpace(entry.Thinking) == "" {
+				entry.Thinking = "adaptive"
+			}
+		}
+
+		prov, err := boot.NewProviderWithProxy(entry, proxySpec)
+		if err != nil {
+			return nil, nil, 0, err
+		}
+		return prov, entry.Price, entry.ContextWindow, nil
+	}
+}
diff --git a/internal/cli/acp_test.go b/internal/cli/acp_test.go
index e6b948fe5..9782bfdd4 100644
--- a/internal/cli/acp_test.go
+++ b/internal/cli/acp_test.go
@@ -1,14 +1,25 @@
 package cli
 
 import (
+	"context"
 	"testing"
 
 	"reasonix/internal/config"
+	"reasonix/internal/netclient"
+	"reasonix/internal/provider"
 	"reasonix/internal/tool"
 
 	_ "reasonix/internal/tool/builtin"
 )
 
+const acpTestProviderKind = "acp-test-provider"
+
+func init() {
+	provider.Register(acpTestProviderKind, func(cfg provider.Config) (provider.Provider, error) {
+		return &acpTestProvider{cfg: cfg}, nil
+	})
+}
+
 func TestACPBuiltinToolsKeepSessionLevelBuiltins(t *testing.T) {
 	dir := t.TempDir()
 	tools := toolMap(acpBuiltinTools(&config.Config{}, dir, []string{dir}))
@@ -26,6 +37,89 @@ func TestACPBuiltinToolsKeepSessionLevelBuiltins(t *testing.T) {
 	}
 }
 
+func TestACPTaskProfileDefaults(t *testing.T) {
+	cfg := config.Default()
+	cfg.Agent.SubagentModel = "default-model"
+	cfg.Agent.SubagentEffort = "high"
+	cfg.Agent.SubagentModels = map[string]string{"task": "task-model"}
+	cfg.Agent.SubagentEfforts = map[string]string{"task": "max"}
+
+	model, effort := acpTaskProfileDefaults(cfg)
+	if model != "task-model" || effort != "max" {
+		t.Fatalf("task profile defaults = %q/%q, want task-model/max", model, effort)
+	}
+
+	cfg.Agent.SubagentModels = nil
+	cfg.Agent.SubagentEfforts = nil
+	model, effort = acpTaskProfileDefaults(cfg)
+	if model != "default-model" || effort != "high" {
+		t.Fatalf("fallback task profile defaults = %q/%q, want default-model/high", model, effort)
+	}
+}
+
+func TestACPSubagentProviderResolverHonorsProfile(t *testing.T) {
+	cfg := config.Default()
+	cfg.Providers = []config.ProviderEntry{
+		{
+			Name:             "parent",
+			Kind:             acpTestProviderKind,
+			Model:            "parent-model",
+			ContextWindow:    111,
+			SupportedEfforts: []string{"low", "high"},
+		},
+		{
+			Name:             "sub",
+			Kind:             acpTestProviderKind,
+			Models:           []string{"sub-model"},
+			Default:          "sub-model",
+			ContextWindow:    222,
+			SupportedEfforts: []string{"low", "high"},
+		},
+	}
+	parent, ok := cfg.ResolveModel("parent")
+	if !ok {
+		t.Fatal("parent model did not resolve")
+	}
+
+	resolve := newACPSubagentProviderResolver(cfg, parent, netclient.ProxySpec{})
+	prov, _, ctxWin, err := resolve("sub/sub-model", "HIGH")
+	if err != nil {
+		t.Fatalf("resolve sub profile: %v", err)
+	}
+	got := prov.(*acpTestProvider).cfg
+	if got.Model != "sub-model" || got.Extra["effort"] != "high" || ctxWin != 222 {
+		t.Fatalf("resolved profile = model:%q effort:%v ctx:%d, want sub-model/high/222", got.Model, got.Extra["effort"], ctxWin)
+	}
+
+	prov, _, ctxWin, err = resolve("", "low")
+	if err != nil {
+		t.Fatalf("resolve effort-only profile: %v", err)
+	}
+	got = prov.(*acpTestProvider).cfg
+	if got.Model != "parent-model" || got.Extra["effort"] != "low" || ctxWin != 111 {
+		t.Fatalf("effort-only profile = model:%q effort:%v ctx:%d, want parent-model/low/111", got.Model, got.Extra["effort"], ctxWin)
+	}
+}
+
+func TestACPSubagentProviderResolverRejectsInvalidEffort(t *testing.T) {
+	cfg := config.Default()
+	cfg.Providers = []config.ProviderEntry{{
+		Name:             "parent",
+		Kind:             acpTestProviderKind,
+		Model:            "parent-model",
+		SupportedEfforts: []string{"low", "high"},
+	}}
+	parent, ok := cfg.ResolveModel("parent")
+	if !ok {
+		t.Fatal("parent model did not resolve")
+	}
+
+	resolve := newACPSubagentProviderResolver(cfg, parent, netclient.ProxySpec{})
+	if _, _, _, err := resolve("", "max"); err == nil {
+		t.Fatal("invalid effort should fail before ACP task falls back to the parent profile")
+	}
+}
+
 func toolMap(tools []tool.Tool) map[string]tool.Tool {
 	out := make(map[string]tool.Tool, len(tools))
 	for _, t := range tools {
@@ -41,3 +135,16 @@ func toolNames(tools map[string]tool.Tool) []string {
 	}
 	return out
 }
+
+type acpTestProvider struct {
+	cfg provider.Config
+}
+
+func (p *acpTestProvider) Name() string { return p.cfg.Name }
+
+func (p *acpTestProvider) Stream(context.Context, provider.Request) (<-chan provider.Chunk, error) {
+	ch := make(chan provider.Chunk, 1)
+	ch <- provider.Chunk{Type: provider.ChunkDone}
+	close(ch)
+	return ch, nil
+}
diff --git a/internal/cli/chat_tui_test.go b/internal/cli/chat_tui_test.go
index 950ba3704..da64b1b36 100644
--- a/internal/cli/chat_tui_test.go
+++ b/internal/cli/chat_tui_test.go
@@ -550,8 +550,10 @@ func isolateUserConfig(t *testing.T) {
 	t.Helper()
 	root := t.TempDir()
 	t.Setenv("HOME", root)
+	t.Setenv("USERPROFILE", root)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(root, "config"))
 	t.Setenv("AppData", filepath.Join(root, "AppData")) // os.UserConfigDir reads AppData on Windows
+	t.Setenv("APPDATA", filepath.Join(root, "AppData"))
 	t.Chdir(root)
 }
 
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index 19fb400bb..7b81e327c 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -478,10 +478,11 @@ func chatREPL(args []string) int {
 
 // setupTargets is where the wizard writes: the TOML config and the secrets file.
 // Keys always go to the reasonix-owned global credentials file so they never land
-// in a project's own .env; only the config location is project-local under --local.
+// in a project's own .env.
 type setupTargets struct {
-	config string
-	env    string
+	config  string
+	env     string
+	invalid bool
 }
 
 // defaultConfigTarget is the user-global config file, falling back to a
@@ -502,17 +503,19 @@ func defaultEnvTarget() string {
 	return ".env"
 }
 
-// resolveSetupTargets picks where `reasonix setup` writes. Keys always go to the
-// global env. The config goes to the user-global dir by default, to ./reasonix.toml
-// under --local, or to an explicit path argument when given.
+// resolveSetupTargets picks where `reasonix setup` writes. The config always goes
+// to the global ~/.reasonix/config.toml. Custom output paths and --local are
+// rejected because the loader no longer reads project-local setup outputs.
 func resolveSetupTargets(args []string) setupTargets {
 	t := setupTargets{config: defaultConfigTarget(), env: defaultEnvTarget()}
 	for _, a := range args {
 		switch a {
 		case "--local", "-l":
-			t.config = "reasonix.toml"
+			fmt.Fprintln(os.Stderr, "error: --local is no longer supported. Configuration is always global (~/.reasonix/). To import an existing project config, use:\n  reasonix config import --from reasonix.toml")
+			return setupTargets{invalid: true}
 		default:
-			t.config = a
+			fmt.Fprintf(os.Stderr, "error: setup path %q is no longer supported. Configuration is always written to ~/.reasonix/config.toml. To import an existing project config, use:\n  reasonix config import --from %s\n", a, a)
+			return setupTargets{invalid: true}
 		}
 	}
 	return t
@@ -527,12 +530,15 @@ func displayPath(p string) string {
 }
 
 // setupConfig runs the configuration wizard (the `reasonix setup` command),
-// writing config.toml to the user-global dir (or ./reasonix.toml under --local)
-// and API keys to the reasonix-owned global .env — never a project's own .env.
+// writing config.toml to the user-global dir and API keys to the reasonix-owned
+// global .env — never a project's own .env.
 // Project memory is a separate concern — the in-session `/init` skill generates
 // AGENTS.md (see initHint).
 func setupConfig(args []string) int {
 	t := resolveSetupTargets(args)
+	if t.invalid {
+		return 2
+	}
 	path := t.config
 	if _, err := os.Stat(path); err == nil {
 		// Non-interactive must not clobber an existing config silently.
@@ -1540,15 +1546,89 @@ func configCommand(args []string) int {
 	switch args[0] {
 	case "auto-plan":
 		return configAutoPlanCommand(args[1:])
+	case "paths":
+		return configPathsCommand()
+	case "doctor":
+		return configDoctorCommand()
+	case "import":
+		return configImportCommand(args[1:])
 	default:
 		configUsage()
 		return 2
 	}
 }
 
+func configPathsCommand() int {
+	fmt.Println("Rawsonix configuration paths:")
+	fmt.Println("  root:          ", displayPath(config.UserRootDir()))
+	fmt.Println("  config.toml:   ", displayPath(config.UserConfigPath()))
+	fmt.Println("  mcp.toml:      ", displayPath(config.UserMCPConfigPath()))
+	fmt.Println("  skills.toml:   ", displayPath(config.UserSkillsConfigPath()))
+	fmt.Println("  credentials:   ", displayPath(config.UserCredentialsPath()))
+	fmt.Println("  sessions:      ", displayPath(config.SessionDir()))
+	fmt.Println("  archive:       ", displayPath(config.ArchiveDir()))
+	fmt.Println("  cache:         ", displayPath(config.CacheDir()))
+	fmt.Println("  backups:       ", displayPath(config.BackupDir()))
+	return 0
+}
+
+func configDoctorCommand() int {
+	cfg, err := config.Load()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "config load error: %v\n", err)
+	}
+	_ = cfg
+	config.DetectIgnoredProjectFiles(".")
+	diags := config.CollectDiagnostics()
+	summary := config.RenderDiagnostics(diags)
+	if summary != "" {
+		fmt.Print(summary)
+	} else {
+		fmt.Println("No configuration issues detected.")
+	}
+	fmt.Println("\nGlobal config:", displayPath(config.UserConfigPath()))
+	fmt.Println("MCP config:   ", displayPath(config.UserMCPConfigPath()))
+	fmt.Println("Skills config:", displayPath(config.UserSkillsConfigPath()))
+	return 0
+}
+
+func configImportCommand(args []string) int {
+	if len(args) == 0 {
+		fmt.Fprintln(os.Stderr, "usage: reasonix config import --from <path>")
+		return 2
+	}
+	from := ""
+	for i := 0; i < len(args); i++ {
+		switch args[i] {
+		case "--from":
+			if i+1 < len(args) {
+				from = args[i+1]
+				i++
+			}
+		default:
+			fmt.Fprintf(os.Stderr, "unknown flag: %s\n", args[i])
+			return 2
+		}
+	}
+	if from == "" {
+		fmt.Fprintln(os.Stderr, "usage: reasonix config import --from <path>")
+		return 2
+	}
+	imported, skipped, errs := config.ImportConfigFromPath(from)
+	if len(errs) > 0 {
+		for _, e := range errs {
+			fmt.Fprintln(os.Stderr, "error:", e)
+		}
+	}
+	fmt.Printf("imported %d, skipped %d from %s\n", imported, skipped, from)
+	if len(errs) > 0 {
+		return 1
+	}
+	return 0
+}
+
 func configAutoPlanCommand(args []string) int {
 	fs := flag.NewFlagSet("config auto-plan", flag.ContinueOnError)
-	local := fs.Bool("local", false, "write ./reasonix.toml instead of the user config")
 	if err := fs.Parse(args); err != nil {
 		return 2
 	}
@@ -1569,32 +1649,10 @@ func configAutoPlanCommand(args []string) int {
 		return 0
 	}
 	path := config.UserConfigPath()
-	if *local {
-		path = "reasonix.toml"
-	}
 	if path == "" {
 		fmt.Fprintln(os.Stderr, i18n.M.ErrorPrefix, "cannot resolve config path")
 		return 1
 	}
-	if *local {
-		if _, err := os.Stat(path); errors.Is(err, os.ErrNotExist) {
-			probe := config.Default()
-			if err := probe.SetAutoPlan(rest[0]); err != nil {
-				fmt.Fprintln(os.Stderr, i18n.M.ErrorPrefix, err)
-				return 2
-			}
-			mode, err := config.SaveMinimalProjectAutoPlan(path, rest[0])
-			if err != nil {
-				fmt.Fprintln(os.Stderr, i18n.M.ErrorPrefix, err)
-				return 1
-			}
-			fmt.Printf("auto_plan = %q (%s)\n", mode, displayPath(path))
-			return 0
-		} else if err != nil {
-			fmt.Fprintln(os.Stderr, i18n.M.ErrorPrefix, err)
-			return 1
-		}
-	}
 	cfg := config.LoadForEdit(path)
 	if err := cfg.SetAutoPlan(rest[0]); err != nil {
 		fmt.Fprintln(os.Stderr, i18n.M.ErrorPrefix, err)
@@ -1610,12 +1668,15 @@ func configAutoPlanCommand(args []string) int {
 
 func configUsage() {
 	fmt.Print(`Usage:
-  reasonix config auto-plan [--local] [off|on]
+  reasonix config auto-plan [off|on]
+  reasonix config paths
+  reasonix config doctor
+  reasonix config import --from <path>
 `)
 }
 
 func configAutoPlanUsage() {
 	fmt.Print(`Usage:
-  reasonix config auto-plan [--local] [off|on]
+  reasonix config auto-plan [off|on]
 `)
 }
diff --git a/internal/cli/cli_test.go b/internal/cli/cli_test.go
index b143a6565..0c73d187c 100644
--- a/internal/cli/cli_test.go
+++ b/internal/cli/cli_test.go
@@ -122,7 +122,7 @@ command = "legacy-bin"
 	if err != nil {
 		t.Fatalf("read migrated user config: %v", err)
 	}
-	for _, want := range []string{`config_version = 2`, `[desktop]`, `name    = "legacy-cli"`} {
+	for _, want := range []string{`config_version = 2`, `[desktop]`} {
 		if !strings.Contains(string(body), want) {
 			t.Fatalf("migrated config missing %q:\n%s", want, body)
 		}
@@ -169,7 +169,7 @@ func TestConfigAutoPlanCommandWritesUserConfig(t *testing.T) {
 	}
 }
 
-func TestConfigAutoPlanLocalCreatesMinimalProjectOverride(t *testing.T) {
+func TestConfigAutoPlanSetsGlobalConfig(t *testing.T) {
 	isolateCLIConfigHome(t)
 
 	userCfg := config.Default()
@@ -179,23 +179,12 @@ func TestConfigAutoPlanLocalCreatesMinimalProjectOverride(t *testing.T) {
 	}
 
 	out := captureStdout(t, func() {
-		if rc := Run([]string{"config", "auto-plan", "--local", "on"}, "test-version"); rc != 0 {
-			t.Fatalf("config auto-plan --local rc = %d, want 0", rc)
+		if rc := Run([]string{"config", "auto-plan", "on"}, "test-version"); rc != 0 {
+			t.Fatalf("config auto-plan rc = %d, want 0", rc)
 		}
 	})
 	if !strings.Contains(out, `auto_plan = "on"`) {
-		t.Fatalf("config auto-plan --local output = %q", out)
-	}
-
-	body, err := os.ReadFile("reasonix.toml")
-	if err != nil {
-		t.Fatalf("read project config: %v", err)
-	}
-	if strings.Contains(string(body), "default_model") {
-		t.Fatalf("project auto-plan override should not pin default_model:\n%s", body)
-	}
-	if !strings.Contains(string(body), "[agent]") || !strings.Contains(string(body), `auto_plan = "on"`) {
-		t.Fatalf("project config missing auto_plan override:\n%s", body)
+		t.Fatalf("config auto-plan output = %q", out)
 	}
 
 	cfg, err := config.Load()
@@ -206,7 +195,21 @@ func TestConfigAutoPlanLocalCreatesMinimalProjectOverride(t *testing.T) {
 		t.Fatalf("default_model = %q, want global mimo-pro", cfg.DefaultModel)
 	}
 	if cfg.Agent.AutoPlan != "on" {
-		t.Fatalf("auto_plan = %q, want local on", cfg.Agent.AutoPlan)
+		t.Fatalf("auto_plan = %q, want on", cfg.Agent.AutoPlan)
+	}
+}
+
+func TestSetupRejectsCustomPath(t *testing.T) {
+	isolateCLIConfigHome(t)
+
+	if rc := Run([]string{"setup", "reasonix.toml"}, "test-version"); rc != 2 {
+		t.Fatalf("setup custom path rc = %d, want 2", rc)
+	}
+	if _, err := os.Stat("reasonix.toml"); !os.IsNotExist(err) {
+		t.Fatalf("setup custom path should not write project config, stat err=%v", err)
+	}
+	if _, err := os.Stat(config.UserConfigPath()); !os.IsNotExist(err) {
+		t.Fatalf("setup custom path should not write global config after rejecting the path, stat err=%v", err)
 	}
 }
 
diff --git a/internal/cli/mcp.go b/internal/cli/mcp.go
index fb2934cab..b9df53bbc 100644
--- a/internal/cli/mcp.go
+++ b/internal/cli/mcp.go
@@ -182,8 +182,8 @@ func mcpList() int {
 	listed := 0
 	// CodeGraph is a built-in server injected by boot, not a [[plugins]] entry, so
 	// report its resolved status here too. It is listed even when disabled, matching
-	// the MCP manager where the user can enable it and choose a startup tier.
-	codegraphMeta := fmt.Sprintf(" [auto_start=%v tier=%s]", cfg.Codegraph.Enabled, cfg.Codegraph.ResolvedTier())
+	// the MCP manager where the user can enable it.
+	codegraphMeta := fmt.Sprintf(" [enabled=%v auto_install=%v]", cfg.Codegraph.Enabled, cfg.Codegraph.AutoInstall)
 	if bin, ok := codegraph.Resolve(cfg.Codegraph.Path); ok {
 		fmt.Printf("%-16s (stdio, built-in)%s  %s serve --mcp\n", "codegraph", codegraphMeta, bin)
 	} else {
@@ -214,6 +214,7 @@ func mcpList() int {
 	if listed == 0 {
 		fmt.Println("no MCP servers configured")
 	}
+	fmt.Println("\nMCP servers are stored in", config.UserMCPConfigPath())
 	return 0
 }
 
@@ -223,20 +224,11 @@ func mcpAddCLI(args []string) int {
 		fmt.Fprintln(os.Stderr, err)
 		return 2
 	}
-	cfg, err := config.Load()
-	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		return 1
-	}
-	if err := cfg.UpsertPlugin(entry); err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		return 1
-	}
-	if err := cfg.Save(); err != nil {
+	if err := config.UpsertMCPPlugin(entry); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		return 1
 	}
-	fmt.Printf("added MCP server %q — loads on the next session (or run `/mcp add` inside chat to connect it live now)\n", entry.Name)
+	fmt.Printf("added MCP server %q to %s — loads on the next session (or run `/mcp add` inside chat to connect it live now)\n", entry.Name, config.UserMCPConfigPath())
 	return 0
 }
 
@@ -246,17 +238,13 @@ func mcpRemoveCLI(args []string) int {
 		return 2
 	}
 	name := args[0]
-	cfg, err := config.Load()
+	found, err := config.RemoveMCPPlugin(name)
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		return 1
 	}
-	if !cfg.RemovePlugin(name) {
-		fmt.Fprintf(os.Stderr, "no MCP server named %q in config\n", name)
-		return 1
-	}
-	if err := cfg.Save(); err != nil {
-		fmt.Fprintln(os.Stderr, err)
+	if !found {
+		fmt.Fprintf(os.Stderr, "no MCP server named %q in %s\n", name, config.UserMCPConfigPath())
 		return 1
 	}
 	fmt.Printf("removed MCP server %q\n", name)
@@ -264,7 +252,7 @@ func mcpRemoveCLI(args []string) int {
 }
 
 func mcpUsage() {
-	fmt.Println(`Manage MCP servers (persisted to reasonix.toml).
+	fmt.Println(`Manage MCP servers (persisted to ` + config.UserMCPConfigPath() + `).
 
 Usage:
   reasonix mcp list
diff --git a/internal/cli/mcp_manager.go b/internal/cli/mcp_manager.go
index 11b2b9bba..6400f78df 100644
--- a/internal/cli/mcp_manager.go
+++ b/internal/cli/mcp_manager.go
@@ -93,15 +93,7 @@ type mcpExternalDoneMsg struct {
 	err    error
 }
 
-var mcpModeChoices = []struct {
-	tier  string
-	label string
-	desc  string
-}{
-	{"lazy", "Connect when this MCP is used", "Do not pre-connect; connect automatically on first tool use."},
-	{"background", "Connect in background after session starts", "New sessions connect automatically without blocking chat."},
-	{"eager", "Connect before chat starts", "New sessions wait for this MCP before chat begins."},
-}
+var mcpTierChoices = []string{"background", "eager", "lazy"}
 
 func (m *chatTUI) openMCPManager(name string) {
 	m.mcp = &mcpManager{stage: mcpStageList, snapshot: m.buildMCPSnapshot()}
@@ -159,6 +151,8 @@ func (m chatTUI) handleMCPManagerKey(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
 			if p.sel < len(p.snapshot.servers)-1 {
 				p.sel++
 			}
+		case "r":
+			p.snapshot = m.buildMCPSnapshot()
 		case "enter", "right", "l":
 			if len(p.snapshot.servers) > 0 {
 				p.name = p.snapshot.servers[p.sel].Name
@@ -199,15 +193,15 @@ func (m chatTUI) handleMCPManagerKey(msg tea.KeyPressMsg) (tea.Model, tea.Cmd) {
 				p.mode--
 			}
 		case "down", "j":
-			if p.mode < len(mcpModeChoices)-1 {
+			if p.mode < len(mcpTierChoices)-1 {
 				p.mode++
 			}
 		case "enter":
-			return m.applyMCPMode(mcpModeChoices[p.mode].tier)
+			return m.applyMCPMode(mcpTierChoices[p.mode])
 		default:
-			if idx, ok := numberKeyIndex(msg.String(), len(mcpModeChoices)); ok {
+			if idx, ok := numberKeyIndex(msg.String(), len(mcpTierChoices)); ok {
 				p.mode = idx
-				return m.applyMCPMode(mcpModeChoices[p.mode].tier)
+				return m.applyMCPMode(mcpTierChoices[p.mode])
 			}
 		}
 	case mcpStageConfirmRemove:
@@ -268,8 +262,8 @@ func (p *mcpManager) clamp() {
 	if p.mode < 0 {
 		p.mode = 0
 	}
-	if p.mode >= len(mcpModeChoices) {
-		p.mode = len(mcpModeChoices) - 1
+	if p.mode >= len(mcpTierChoices) {
+		p.mode = len(mcpTierChoices) - 1
 	}
 	if p.confirm < 0 || p.confirm > 1 {
 		p.confirm = 0
diff --git a/internal/cli/mcp_manager_actions.go b/internal/cli/mcp_manager_actions.go
index 21d31e386..254bb33af 100644
--- a/internal/cli/mcp_manager_actions.go
+++ b/internal/cli/mcp_manager_actions.go
@@ -211,7 +211,7 @@ func (m chatTUI) applyMCPMode(tier string) (tea.Model, tea.Cmd) {
 		m.notice(fmt.Sprintf("mcp mode: no configured MCP server named %q", v.Name))
 		return m, nil
 	}
-	if err := cfg.Save(); err != nil {
+	if err := config.SaveMCPTOML(cfg.Plugins); err != nil {
 		m.notice("mcp mode: " + err.Error())
 		return m, nil
 	}
@@ -349,8 +349,8 @@ func (m chatTUI) clearMCPAuthentication(v mcpServerView) (tea.Model, tea.Cmd) {
 
 func mcpModeIndex(tier string) int {
 	tier = normalizeMCPTierForCLI(tier)
-	for i, choice := range mcpModeChoices {
-		if choice.tier == tier {
+	for i, choice := range mcpTierChoices {
+		if choice == tier {
 			return i
 		}
 	}
@@ -363,22 +363,21 @@ func normalizeMCPTierForCLI(tier string) string {
 		return "eager"
 	case "background":
 		return "background"
+	case "":
+		return "background"
 	default:
 		return "lazy"
 	}
 }
 
 func mcpConfigLocation() string {
-	if path := config.SourcePath(); path != "" {
+	if path := config.UserMCPConfigPath(); path != "" {
 		return path
 	}
-	if _, err := os.Stat(".mcp.json"); err == nil {
-		return ".mcp.json"
-	}
 	if path := config.UserConfigPath(); path != "" {
 		return path
 	}
-	return "reasonix.toml"
+	return ""
 }
 
 type mcpEditConfigLaunch struct {
diff --git a/internal/cli/mcp_manager_view.go b/internal/cli/mcp_manager_view.go
index bc2eeaeea..8924fbb9f 100644
--- a/internal/cli/mcp_manager_view.go
+++ b/internal/cli/mcp_manager_view.go
@@ -25,8 +25,6 @@ func (p *mcpManager) render(width int) string {
 		return managerContentPanelStyle(w).Render(p.renderTools(w))
 	case mcpStageLogs:
 		return managerContentPanelStyle(w).Render(p.renderLogs(w))
-	case mcpStageMode:
-		return managerContentPanelStyle(w).Render(p.renderMode(w))
 	case mcpStageConfirmRemove:
 		return managerContentPanelStyle(w).Render(p.renderConfirmRemove(w))
 	case mcpStageConfirmClearAuth:
@@ -39,18 +37,16 @@ func (p *mcpManager) render(width int) string {
 func (p *mcpManager) footerHint() string {
 	switch p.stage {
 	case mcpStageDetail:
-		return "↑/↓ navigate · Enter to select · Esc to back"
+		return "↑/↓ navigate · r refresh · Enter to select · Esc to back"
 	case mcpStageTools, mcpStageLogs:
 		return "Esc to back"
-	case mcpStageMode:
-		return "Enter to apply · Esc to back"
 	case mcpStageConfirmRemove, mcpStageConfirmClearAuth:
 		return "Enter to select · y confirm · n cancel · Esc to back"
 	default:
 		if len(p.snapshot.servers) == 0 {
 			return "↑/↓ navigate · Enter to confirm · Esc to cancel"
 		}
-		return "↑/↓ navigate · Enter for details · Esc to close"
+		return "↑/↓ navigate · r refresh · Enter for details · Esc to close"
 	}
 }
 
@@ -147,9 +143,6 @@ func (p *mcpManager) renderDetail(width int) string {
 		}
 		writeMCPDetailField(&b, "Config location", loc)
 	}
-	if v.Configured {
-		writeMCPDetailField(&b, "Connection mode", mcpModeLabel(v.Tier))
-	}
 	writeMCPDetailField(&b, "Capabilities", mcpCapabilitiesText(v))
 	writeMCPDetailField(&b, "Tools", countText(v.Tools, "tool"))
 	if line := mcpCommandLine(v); line != "" {
@@ -212,22 +205,6 @@ func (p *mcpManager) renderLogs(width int) string {
 	return strings.TrimRight(b.String(), "\n")
 }
 
-func (p *mcpManager) renderMode(width int) string {
-	v, ok := p.selectedServer()
-	if !ok {
-		return "MCP server not found\n\n" + dim("Esc to back")
-	}
-	var b strings.Builder
-	fmt.Fprintf(&b, "Connection mode for %s\n\n", bold(v.Name))
-	for i, choice := range mcpModeChoices {
-		active := choice.tier == v.Tier
-		line := rowLine(i == p.mode, i+1, "", choice.label, active)
-		b.WriteString(line + "\n")
-		b.WriteString(dim("       "+viewCompactText(choice.desc, viewBudget(width, 7))) + "\n")
-	}
-	return strings.TrimRight(b.String(), "\n")
-}
-
 func (p *mcpManager) renderConfirmRemove(width int) string {
 	v, ok := p.selectedServer()
 	if !ok {
@@ -317,7 +294,6 @@ func appendMCPFailureSecondaryActions(out []mcpActionItem, v mcpServerView, conf
 
 func appendMCPConfigActions(out []mcpActionItem, v mcpServerView, configPath string) []mcpActionItem {
 	if v.Configured {
-		out = append(out, mcpActionItem{mcpActionMode, "Change connection mode"})
 		if !v.BuiltIn && configPath != "" {
 			out = append(out, mcpActionItem{mcpActionEdit, "Edit config"})
 		}
@@ -394,12 +370,3 @@ func mcpCommandLine(v mcpServerView) string {
 	}
 	return strings.TrimSpace(v.Command + " " + strings.Join(v.Args, " "))
 }
-
-func mcpModeLabel(tier string) string {
-	for _, choice := range mcpModeChoices {
-		if choice.tier == normalizeMCPTierForCLI(tier) {
-			return choice.label
-		}
-	}
-	return mcpModeChoices[0].label
-}
diff --git a/internal/cli/mcp_test.go b/internal/cli/mcp_test.go
index db160adda..38b1c5b33 100644
--- a/internal/cli/mcp_test.go
+++ b/internal/cli/mcp_test.go
@@ -2,6 +2,7 @@ package cli
 
 import (
 	"errors"
+	"os"
 	"reflect"
 	"strings"
 	"testing"
@@ -382,19 +383,19 @@ func TestMCPEditConfigLaunchUsesSystemDefaultLast(t *testing.T) {
 	}
 }
 
-func TestApplyMCPModePersistsTier(t *testing.T) {
+func TestApplyMCPModeDropsLegacyTier(t *testing.T) {
 	isolateUserConfig(t)
 	cfg := config.Default()
 	cfg.Plugins = []config.PluginEntry{{Name: "github", Command: "npx", Args: []string{"server"}, Tier: "lazy"}}
-	if err := cfg.SaveTo("reasonix.toml"); err != nil {
-		t.Fatalf("save config: %v", err)
+	if err := config.SaveMCPTOML(cfg.Plugins); err != nil {
+		t.Fatalf("save mcp.toml: %v", err)
 	}
 
 	m := newTestChatTUI()
 	m.mcp = &mcpManager{
 		stage: mcpStageMode,
 		name:  "github",
-		snapshot: mcpSnapshot{configPath: "reasonix.toml", servers: []mcpServerView{{
+		snapshot: mcpSnapshot{configPath: config.UserMCPConfigPath(), servers: []mcpServerView{{
 			Name: "github", Transport: "stdio", Status: "deferred", Configured: true, Tier: "lazy",
 		}}},
 	}
@@ -404,8 +405,15 @@ func TestApplyMCPModePersistsTier(t *testing.T) {
 	if err != nil {
 		t.Fatalf("load config: %v", err)
 	}
-	if len(loaded.Plugins) != 1 || loaded.Plugins[0].Tier != "background" {
-		t.Fatalf("tier not persisted, plugins=%+v", loaded.Plugins)
+	if len(loaded.Plugins) != 1 || loaded.Plugins[0].Tier != "" {
+		t.Fatalf("tier should be migrated away, plugins=%+v", loaded.Plugins)
+	}
+	raw, err := os.ReadFile(config.UserMCPConfigPath())
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	if strings.Contains(string(raw), "\ntier") {
+		t.Fatalf("legacy tier should not be written back:\n%s", raw)
 	}
 }
 
@@ -414,7 +422,7 @@ func TestApplyMCPModeRecordsPluginConnectFailure(t *testing.T) {
 	t.Setenv("PATH", "")
 	cfg := config.Default()
 	cfg.Plugins = []config.PluginEntry{{Name: "broken", Command: "definitely-missing-reasonix-mcp", Tier: "lazy"}}
-	if err := cfg.SaveTo("reasonix.toml"); err != nil {
+	if err := config.SaveMCPTOML(cfg.Plugins); err != nil {
 		t.Fatalf("save config: %v", err)
 	}
 
@@ -425,7 +433,7 @@ func TestApplyMCPModeRecordsPluginConnectFailure(t *testing.T) {
 	m.mcp = &mcpManager{
 		stage: mcpStageMode,
 		name:  "broken",
-		snapshot: mcpSnapshot{configPath: "reasonix.toml", servers: []mcpServerView{{
+		snapshot: mcpSnapshot{configPath: config.UserMCPConfigPath(), servers: []mcpServerView{{
 			Name: "broken", Transport: "stdio", Status: "deferred", Configured: true, Tier: "lazy",
 		}}},
 	}
diff --git a/internal/cli/skill_hooks.go b/internal/cli/skill_hooks.go
index b163c8447..ec439ebef 100644
--- a/internal/cli/skill_hooks.go
+++ b/internal/cli/skill_hooks.go
@@ -206,10 +206,8 @@ func enableVerb(enabled bool) string {
 
 func (m *chatTUI) skillNew(name string, global bool) {
 	st := m.skillStore()
-	scope := skill.ScopeProject
-	if global || !st.HasProjectScope() {
-		scope = skill.ScopeGlobal
-	}
+	// Skills are always global now; project-scoped skills are no longer supported.
+	scope := skill.ScopeGlobal
 	path, err := st.Create(name, scope)
 	if err != nil {
 		m.notice("skill new: " + err.Error())
@@ -226,10 +224,12 @@ func (m *chatTUI) skillPaths() {
 func (m *chatTUI) skillStore() *skill.Store {
 	cwd, _ := os.Getwd()
 	var custom []string
+	maxDepth := 3
 	if cfg, err := config.Load(); err == nil {
 		custom = cfg.SkillCustomPaths()
+		maxDepth = cfg.SkillMaxDepth()
 	}
-	return skill.New(skill.Options{ProjectRoot: cwd, CustomPaths: custom})
+	return skill.New(skill.Options{ProjectRoot: cwd, CustomPaths: custom, MaxDepth: maxDepth})
 }
 
 func (m *chatTUI) runHooksSubcommand(input string) {
diff --git a/internal/config/backup.go b/internal/config/backup.go
new file mode 100644
index 000000000..6d221c84d
--- /dev/null
+++ b/internal/config/backup.go
@@ -0,0 +1,89 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+
+	"reasonix/internal/fileutil"
+)
+
+const maxBackupsPerType = 5
+
+// backupBeforeWrite copies the file at path to ~/.reasonix/backups/config/<name>-<timestamp>
+// before it is overwritten. An absent file is silently skipped.
+func backupBeforeWrite(path string) error {
+	dir := BackupDir()
+	if dir == "" {
+		return nil
+	}
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		return nil
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return err
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return err
+	}
+	base := filepath.Base(path)
+	ext := filepath.Ext(base)
+	stem := strings.TrimSuffix(base, ext)
+	ts := time.Now().UTC().Format("20060102T150405")
+	backupPath := filepath.Join(dir, fmt.Sprintf("%s-%s%s", stem, ts, ext))
+
+	if err := os.WriteFile(backupPath, data, 0o600); err != nil {
+		return err
+	}
+	rotateBackups(filepath.Join(dir, stem), ext)
+	return nil
+}
+
+// rotateBackups keeps only the most recent maxBackupsPerType backups matching the
+// stem-* pattern.
+func rotateBackups(prefix, ext string) {
+	pattern := filepath.Base(prefix) + "-*" + ext
+	matches, err := filepath.Glob(filepath.Join(filepath.Dir(prefix), pattern))
+	if err != nil || len(matches) <= maxBackupsPerType {
+		return
+	}
+	sort.Sort(sort.Reverse(sort.StringSlice(matches)))
+	for _, m := range matches[maxBackupsPerType:] {
+		os.Remove(m)
+	}
+}
+
+// writeConfigFile writes a config file atomically, with a backup of the previous
+// version. Parent directories are created as needed.
+func writeConfigFile(path, body string) error {
+	if strings.TrimSpace(path) == "" {
+		return fmt.Errorf("save: empty config path")
+	}
+	if err := backupBeforeWrite(path); err != nil {
+		// Nonfatal: if backup fails, still try to save.
+		_ = err
+	}
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return fmt.Errorf("save: create dir: %w", err)
+	}
+	tmp, err := os.CreateTemp(dir, ".reasonix.*.toml.tmp")
+	if err != nil {
+		return fmt.Errorf("save: create temp: %w", err)
+	}
+	tmpPath := tmp.Name()
+	if _, err := tmp.WriteString(body); err != nil {
+		tmp.Close()
+		os.Remove(tmpPath)
+		return fmt.Errorf("save: write: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		os.Remove(tmpPath)
+		return fmt.Errorf("save: close temp: %w", err)
+	}
+	return fileutil.ReplaceFile(tmpPath, path)
+}
diff --git a/internal/config/commanddirs_test.go b/internal/config/commanddirs_test.go
index f1b298989..0c3e1b572 100644
--- a/internal/config/commanddirs_test.go
+++ b/internal/config/commanddirs_test.go
@@ -6,10 +6,6 @@ import (
 	"testing"
 )
 
-// TestCommandDirsIncludeConventions verifies command discovery covers the
-// cross-tool convention dirs (so .claude/commands etc. migrate in) and that the
-// canonical .reasonix project dir is highest priority (last, since command.Load
-// lets a later dir win on a name clash).
 func TestCommandDirsIncludeConventions(t *testing.T) {
 	dirs := CommandDirs()
 	joined := strings.Join(dirs, "\n")
@@ -23,8 +19,11 @@ func TestCommandDirsIncludeConventions(t *testing.T) {
 			t.Errorf("CommandDirs missing %q\ngot:\n%s", want, joined)
 		}
 	}
-	// The project's .reasonix/commands must be the highest-priority (last) entry.
-	if last := dirs[len(dirs)-1]; last != filepath.Join(".reasonix", "commands") {
-		t.Errorf("project .reasonix/commands should be highest priority (last), got %q", last)
+	// Home .reasonix/commands or legacy XDG commands must be last.
+	// On macOS the XDG path is ~/Library/Application Support/reasonix/commands.
+	last := dirs[len(dirs)-1]
+	if !strings.HasSuffix(last, filepath.Join(".reasonix", "commands")) &&
+		!strings.Contains(last, filepath.Join("reasonix", "commands")) {
+		t.Errorf("last entry should be a reasonix commands dir, got %q", last)
 	}
 }
diff --git a/internal/config/config.go b/internal/config/config.go
index 26e2de71a..662b1f161 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -296,6 +296,7 @@ func (c *Config) NetworkProxyMode() string {
 type SkillsConfig struct {
 	Paths          []string `toml:"paths"`
 	DisabledSkills []string `toml:"disabled_skills"`
+	MaxDepth       int      `toml:"max_depth"`
 }
 
 // SkillCustomPaths returns the configured custom skill roots with ${VAR}
@@ -310,6 +311,25 @@ func (c *Config) SkillCustomPaths() []string {
 	return out
 }
 
+// SkillMaxDepth bounds nested skill discovery. Depth 3 favors bundled skill
+// packs while Store keeps nested markdown safe by requiring descriptions.
+func (c *Config) SkillMaxDepth() int {
+	const (
+		defaultDepth = 3
+		maxDepth     = 5
+	)
+	if c == nil || c.Skills.MaxDepth == 0 {
+		return defaultDepth
+	}
+	if c.Skills.MaxDepth < 1 {
+		return 1
+	}
+	if c.Skills.MaxDepth > maxDepth {
+		return maxDepth
+	}
+	return c.Skills.MaxDepth
+}
+
 // DisabledSkillNames returns valid disabled skill identifiers, preserving the
 // first spelling and dropping duplicates/empty entries.
 func (c *Config) DisabledSkillNames() []string {
@@ -419,6 +439,8 @@ type AgentConfig struct {
 	PlannerModel     string            `toml:"planner_model"`
 	SubagentModel    string            `toml:"subagent_model"`
 	SubagentModels   map[string]string `toml:"subagent_models"`
+	SubagentEffort   string            `toml:"subagent_effort"`
+	SubagentEfforts  map[string]string `toml:"subagent_efforts"`
 	// OutputStyle selects a persona/tone block folded into the system prompt at
 	// startup (a built-in like "explanatory"/"learning"/"concise", or a custom
 	// .reasonix/output-styles/<name>.md). Empty = the unmodified prompt.
@@ -557,10 +579,11 @@ type PluginEntry struct {
 	//                  servers whose tools the system prompt depends on.
 	//   "lazy"       — registers placeholder tools immediately (from on-disk
 	//                  schema cache when available) and only spawns the real
-	//                  subprocess on first model use. Default for user plugins.
+	//                  subprocess on first model use. Kept for legacy configs.
 	//   "background" — placeholder + spawn fired at boot but not waited on;
 	//                  swap happens once the spawn finishes.
-	// Empty defaults to "lazy" so adding a plugin never slows the next launch.
+	// Empty defaults to "background" so enabled MCPs connect automatically
+	// without blocking chat. Unknown non-empty values fall back to "lazy".
 	Tier string `toml:"tier"`
 }
 
@@ -581,6 +604,8 @@ func resolvedMCPTier(tier string) string {
 		return "eager"
 	case "background":
 		return "background"
+	case "":
+		return "background"
 	default:
 		return "lazy"
 	}
@@ -679,61 +704,59 @@ func Load() (*Config, error) {
 // each project's reasonix.toml + .env + .mcp.json are resolved independently
 // without changing the process cwd.
 func LoadForRoot(root string) (*Config, error) {
-	root = resolveRoot(root)
-	loadDotEnvForRoot(root)
+	// .env: only global credentials and legacy ~/.env; project .env is no longer read.
+	loadDotEnvGlobal()
 	cfg := Default()
 
-	projectTOML := "reasonix.toml"
-	if root != "." {
-		projectTOML = filepath.Join(root, "reasonix.toml")
-	}
-
-	var tomlSources []string
-	if uc := userConfigPath(); uc != "" {
-		tomlSources = append(tomlSources, uc)
-	}
-	tomlSources = append(tomlSources, projectTOML)
 	sawConfigFile := false
-	for _, path := range tomlSources {
-		if _, err := os.Stat(path); err == nil {
+	if uc := UserConfigPath(); uc != "" {
+		if _, err := os.Stat(uc); err == nil {
 			sawConfigFile = true
+			if err := migrateLegacyMCPTiersFile(uc); err != nil {
+				slog.Warn("config: legacy mcp tier migration failed", "path", uc, "err", err)
+			}
 		}
-		if err := mergeFile(cfg, path); err != nil {
+		if err := mergeFile(cfg, uc); err != nil {
 			return nil, err
 		}
 	}
-	// toml.DecodeFile replaces [[plugins]] wholesale, so cfg.Plugins now holds
-	// only the last file's. Re-merge by name across all sources (later wins) so a
-	// project reasonix.toml doesn't drop the global config's MCP servers.
-	plugins, err := mergeTOMLPlugins(tomlSources)
-	if err != nil {
-		return nil, err
-	}
-	cfg.Plugins = plugins
 
-	// Claude Code's .mcp.json (project root) is read last and merged into
-	// [[plugins]], so a server configured for Claude works here unchanged.
-	// reasonix.toml wins on a name collision (see mergeMCPJSON).
-	mcpFile := mcpJSONFile
-	if root != "." {
-		mcpFile = filepath.Join(root, mcpJSONFile)
+	// MCP: if ~/.reasonix/mcp.toml exists on disk (even if empty), it is the sole
+	// authority — [[plugins]] from config.toml and legacy config.json are ignored.
+	// Good entries are accepted even when some entries fail validation (nonfatal).
+	hasMCPFile := false
+	if mcpPath := UserMCPConfigPath(); mcpPath != "" {
+		if _, statErr := os.Stat(mcpPath); statErr == nil {
+			if err := migrateLegacyMCPTiersFile(mcpPath); err != nil {
+				slog.Warn("config: legacy mcp tier migration failed", "path", mcpPath, "err", err)
+			}
+			hasMCPFile = true
+			plugins, err := loadMCPTOML()
+			cfg.Plugins = plugins // always use what loadMCPTOML returned (may be empty)
+			if err != nil {
+				addLoadDiagnostic("mcp.toml", err.Error())
+			}
+		}
 	}
-	entries, err := loadMCPJSON(mcpFile)
-	if err != nil {
-		return nil, err
+
+	// Load skills config from ~/.reasonix/skills.toml. When the file exists on
+	// disk, it replaces inline [skills] entirely. Otherwise keep inline [skills]
+	// for backward compat.
+	if _, statErr := os.Stat(UserSkillsConfigPath()); statErr == nil {
+		if err := loadSkillsTOML(cfg); err != nil {
+			addLoadDiagnostic("skills.toml", err.Error())
+		}
 	}
-	cfg.mergeMCPJSON(entries)
 
-	// Lowest priority: the v0.x ~/.reasonix/config.json's mcpServers, so upgrading
-	// from the TypeScript line keeps MCP servers without rewriting them. Anything
-	// the v2 config or .mcp.json already declared wins on a name collision.
-	cfg.mergeMCPJSON(loadLegacyMCP(legacyConfigPath()))
+	// Legacy JSON MCP: only read when mcp.toml does NOT exist.
+	if !hasMCPFile {
+		cfg.mergeMCPJSON(loadLegacyMCP(legacyConfigPath()))
+	}
+	normalizePluginCommandLines(cfg)
 	normalizeLegacyEffort(cfg)
+	normalizeLegacyMCPTiers(cfg)
 	normalizeEffortConfig(cfg)
 	backfillDeepSeekPro(cfg)
-	// First run (no config file anywhere): keep CodeGraph off until the user opts
-	// in. An existing config — even one without a [codegraph] section — keeps the
-	// built-in default (on), so an upgrade never silently drops code intelligence.
 	if !sawConfigFile {
 		cfg.Codegraph.Enabled = false
 	}
@@ -795,30 +818,6 @@ func normalizeLegacyEffort(c *Config) {
 	}
 }
 
-// mergeTOMLPlugins merges [[plugins]] across TOML sources by name (later source wins).
-func mergeTOMLPlugins(paths []string) ([]PluginEntry, error) {
-	var merged []PluginEntry
-	index := map[string]int{}
-	for _, path := range paths {
-		if _, err := os.Stat(path); err != nil {
-			continue
-		}
-		var f Config
-		if _, err := toml.DecodeFile(path, &f); err != nil {
-			return nil, fmt.Errorf("config %s: %w", path, err)
-		}
-		for _, p := range f.Plugins {
-			if i, ok := index[p.Name]; ok {
-				merged[i] = p
-				continue
-			}
-			index[p.Name] = len(merged)
-			merged = append(merged, p)
-		}
-	}
-	return merged, nil
-}
-
 // LoadForEdit returns a config to seed the `reasonix setup` wizard when reconfiguring:
 // the built-in defaults with the file at path (if present) decoded on top, so a
 // reconfigure preserves the user's existing providers and agent settings instead
@@ -827,10 +826,17 @@ func mergeTOMLPlugins(paths []string) ([]PluginEntry, error) {
 func LoadForEdit(path string) *Config {
 	loadDotEnv()
 	cfg := Default()
+	if _, err := os.Stat(path); err == nil {
+		if err := migrateLegacyMCPTiersFile(path); err != nil {
+			slog.Warn("config: legacy mcp tier migration failed", "path", path, "err", err)
+		}
+	}
 	if err := mergeFile(cfg, path); err != nil {
 		slog.Warn("config: load for edit failed, using defaults", "path", path, "err", err)
 	}
+	normalizePluginCommandLines(cfg)
 	normalizeLegacyEffort(cfg)
+	normalizeLegacyMCPTiers(cfg)
 	normalizeEffortConfig(cfg)
 	return cfg
 }
@@ -846,77 +852,78 @@ func mergeFile(cfg *Config, path string) error {
 	return nil
 }
 
-func userConfigPath() string {
-	dir, err := os.UserConfigDir()
-	if err != nil {
-		return ""
+// normalizeLegacyMCPTiers keeps loaded legacy config files on the new product
+// behavior: enabled MCP servers connect in the background by default, and the
+// retired per-server startup tier is no longer a user-facing setting.
+func normalizeLegacyMCPTiers(c *Config) {
+	if c == nil {
+		return
+	}
+	c.Codegraph.Tier = ""
+	for i := range c.Plugins {
+		c.Plugins[i].Tier = ""
 	}
-	return filepath.Join(dir, "reasonix", "config.toml")
 }
 
-// UserConfigPath is the user-global config file (~/.config/reasonix/config.toml),
-// or "" when the user config dir can't be resolved.
-func UserConfigPath() string { return userConfigPath() }
-
-// UserCredentialsPath is the reasonix-owned global secrets file, beside
-// config.toml in the user config dir (e.g. ~/.config/reasonix/credentials). It
-// holds KEY=value lines loaded into the environment by loadDotEnv. The setup
-// wizard writes API keys here, deliberately NOT named .env: keys never land in a
-// project's own .env (which can't be selectively gitignored), never get
-// committed, and resolve from any working directory. "" when the user config dir
-// can't be resolved.
-func UserCredentialsPath() string {
-	dir, err := os.UserConfigDir()
+func migrateLegacyMCPTiersFile(path string) error {
+	info, err := os.Stat(path)
 	if err != nil {
-		return ""
+		return err
 	}
-	return filepath.Join(dir, "reasonix", "credentials")
-}
-
-// ArchiveDir is where compacted conversation history is archived for
-// traceability (one timestamped .jsonl per compaction). Empty if the user config
-// directory cannot be resolved, in which case archiving is skipped.
-func ArchiveDir() string {
-	dir, err := os.UserConfigDir()
+	raw, err := os.ReadFile(path)
 	if err != nil {
-		return ""
+		return err
 	}
-	return filepath.Join(dir, "reasonix", "archive")
+	next, changed := stripLegacyMCPTierLines(string(raw))
+	if !changed {
+		return nil
+	}
+	return os.WriteFile(path, []byte(next), info.Mode().Perm())
 }
 
-// SessionDir is where chat sessions are persisted (one .jsonl per session).
-// Used by `reasonix chat --continue` / `--resume` to find the recent ones. Empty
-// if the user config dir can't be resolved — sessions then aren't saved.
-func SessionDir() string {
-	dir, err := os.UserConfigDir()
-	if err != nil {
-		return ""
+func stripLegacyMCPTierLines(raw string) (string, bool) {
+	lines := strings.Split(raw, "\n")
+	section := ""
+	changed := false
+	out := make([]string, 0, len(lines))
+	for _, line := range lines {
+		if header := tomlSectionHeader(line); header != "" {
+			section = header
+		}
+		if (section == "codegraph" || section == "plugins") && isTOMLKeyAssignment(line, "tier") {
+			changed = true
+			continue
+		}
+		out = append(out, line)
 	}
-	return filepath.Join(dir, "reasonix", "sessions")
+	return strings.Join(out, "\n"), changed
 }
 
-// CacheDir is the per-user cache root for derived/regenerable artefacts: MCP
-// handshake snapshots, plugin startup-latency telemetry. Lives beside the
-// existing dirs (UserConfigDir/reasonix/...) so the whole reasonix state tree
-// shares one root the user can wipe in a single rm. Empty when the OS dir is
-// unavailable — callers must tolerate that (caching is best-effort).
-func CacheDir() string {
-	dir, err := os.UserConfigDir()
-	if err != nil {
+func tomlSectionHeader(line string) string {
+	trimmed := strings.TrimSpace(line)
+	if !strings.HasPrefix(trimmed, "[") {
 		return ""
 	}
-	return filepath.Join(dir, "reasonix", "cache")
+	if i := strings.Index(trimmed, "#"); i >= 0 {
+		trimmed = strings.TrimSpace(trimmed[:i])
+	}
+	switch trimmed {
+	case "[codegraph]":
+		return "codegraph"
+	case "[[plugins]]":
+		return "plugins"
+	default:
+		return "other"
+	}
 }
 
-// MemoryUserDir returns the reasonix user config root (…/reasonix), under which
-// the user-global REASONIX.md and the per-project auto-memory store live. Empty
-// when the user config dir can't be resolved, which disables user-scoped memory.
-func MemoryUserDir() string {
-	dir, err := os.UserConfigDir()
-	if err != nil {
-		return ""
+func isTOMLKeyAssignment(line, key string) bool {
+	trimmed := strings.TrimSpace(line)
+	if strings.HasPrefix(trimmed, "#") || !strings.HasPrefix(trimmed, key) {
+		return false
 	}
-	return filepath.Join(dir, "reasonix")
+	rest := strings.TrimSpace(strings.TrimPrefix(trimmed, key))
+	return strings.HasPrefix(rest, "=")
 }
 
 // ConventionDirs are the parent directories scanned for agent assets (skills,
@@ -939,22 +946,16 @@ func conventionSubdirsAsc(base, sub string) []string {
 	return out
 }
 
-// CommandDirs returns the directories scanned for custom slash commands, lowest
-// priority first, so a later (more specific) directory overrides an earlier one
-// on a name clash. Order: home-dir convention dirs (~/.claude/commands … ~/.reasonix/commands),
-// the legacy XDG user dir (~/.config/reasonix/commands), then the project's
-// convention dirs (.claude/commands … .reasonix/commands). Scanning the .claude /
-// .agents / .agent dirs lets commands authored for other agent tools (same .md +
-// frontmatter format) work here unchanged.
+// CommandDirs returns the global directories scanned for custom slash commands.
+// Only global convention dirs + legacy XDG user dir are scanned; project dirs are
+// no longer included.
 func CommandDirs() []string {
 	return CommandDirsForRoot(".")
 }
 
-// CommandDirsForRoot is like CommandDirs but resolves the project convention
-// dirs under root instead of the current working directory. Global (home/XDG)
-// dirs are unchanged — they are always user-scoped.
+// CommandDirsForRoot resolves global command directories only. Project convention
+// dirs are no longer scanned.
 func CommandDirsForRoot(root string) []string {
-	root = resolveRoot(root)
 	var dirs []string
 	if home, err := os.UserHomeDir(); err == nil {
 		dirs = append(dirs, conventionSubdirsAsc(home, "commands")...)
@@ -962,7 +963,6 @@ func CommandDirsForRoot(root string) []string {
 	if dir, err := os.UserConfigDir(); err == nil {
 		dirs = append(dirs, filepath.Join(dir, "reasonix", "commands")) // legacy XDG user dir
 	}
-	dirs = append(dirs, conventionSubdirsAsc(root, "commands")...)
 	return dirs
 }
 
@@ -971,18 +971,10 @@ func SourcePath() string {
 	return SourcePathForRoot(".")
 }
 
-// SourcePathForRoot returns the highest-priority config file that exists under
-// root, or "" if none. Equivalent to SourcePath() when root is ".".
+// SourcePathForRoot returns only the global config path — project reasonix.toml
+// is no longer read.
 func SourcePathForRoot(root string) string {
-	root = resolveRoot(root)
-	projectTOML := "reasonix.toml"
-	if root != "." {
-		projectTOML = filepath.Join(root, "reasonix.toml")
-	}
-	if _, err := os.Stat(projectTOML); err == nil {
-		return projectTOML
-	}
-	if uc := userConfigPath(); uc != "" {
+	if uc := UserConfigPath(); uc != "" {
 		if _, err := os.Stat(uc); err == nil {
 			return uc
 		}
diff --git a/internal/config/diagnostic.go b/internal/config/diagnostic.go
new file mode 100644
index 000000000..201018b61
--- /dev/null
+++ b/internal/config/diagnostic.go
@@ -0,0 +1,114 @@
+package config
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// ConfigDiagnostic records issues found during config loading that don't prevent
+// startup: malformed optional files, ignored project-level files, migration state.
+type ConfigDiagnostic struct {
+	MalformedFiles  []string `json:"malformed_files,omitempty"`
+	IgnoredFiles    []string `json:"ignored_files,omitempty"`
+	MigrationStatus string   `json:"migration_status,omitempty"`
+	ImportSkipped   int      `json:"import_skipped,omitempty"`
+	ImportImported  int      `json:"import_imported,omitempty"`
+	ImportErrors    []string `json:"import_errors,omitempty"`
+}
+
+var loadDiags ConfigDiagnostic
+
+func addLoadDiagnostic(file, msg string) {
+	loadDiags.MalformedFiles = append(loadDiags.MalformedFiles, fmt.Sprintf("%s: %s", file, msg))
+}
+
+// CollectDiagnostics returns the accumulated load-time diagnostics and resets.
+func CollectDiagnostics() ConfigDiagnostic {
+	d := loadDiags
+	loadDiags = ConfigDiagnostic{}
+	return d
+}
+
+// DetectIgnoredProjectFiles checks the given root directory for project-level
+// config files that are now ignored (reasonix.toml, .mcp.json, .reasonix/*,
+// .env) and records them in diagnostics.
+func DetectIgnoredProjectFiles(root string) {
+	root = resolveRoot(root)
+	if root == "." {
+		if wd, err := os.Getwd(); err == nil {
+			root = wd
+		}
+	}
+	// Files we can import via `reasonix config import --from`
+	importable := map[string]bool{
+		".toml": true,
+		".json": true,
+	}
+	// Top-level files
+	for _, name := range []string{"reasonix.toml", ".mcp.json", ".env"} {
+		p := filepath.Join(root, name)
+		info, err := os.Stat(p)
+		if err != nil {
+			continue
+		}
+		ext := strings.ToLower(filepath.Ext(name))
+		redacted := redactPath(p)
+		if importable[ext] {
+			loadDiags.IgnoredFiles = append(loadDiags.IgnoredFiles,
+				fmt.Sprintf("%s (file) — use `reasonix config import --from %s` to migrate", redacted, redacted))
+		} else {
+			loadDiags.IgnoredFiles = append(loadDiags.IgnoredFiles,
+				fmt.Sprintf("%s (file) — project-level .env is no longer read; move settings to %s", redacted, redactPath(UserCredentialsPath())))
+		}
+		_ = info
+	}
+	// Convention directory entries are skills/commands — not importable one-by-one
+	for _, c := range ConventionDirs {
+		for _, sub := range []string{"skills", "commands"} {
+			p := filepath.Join(root, c, sub)
+			if info, err := os.Stat(p); err == nil && info.IsDir() {
+				redacted := redactPath(p)
+				loadDiags.IgnoredFiles = append(loadDiags.IgnoredFiles,
+					fmt.Sprintf("%s (directory) — project-level %s are no longer scanned; move them to ~/.reasonix/%s or use custom paths in skills.toml", redacted, sub, sub))
+			}
+		}
+	}
+}
+
+// RenderDiagnostics returns a human-readable summary of load-time diagnostics.
+func RenderDiagnostics(d ConfigDiagnostic) string {
+	if len(d.MalformedFiles) == 0 && len(d.IgnoredFiles) == 0 && d.MigrationStatus == "" {
+		return ""
+	}
+	var b strings.Builder
+	b.WriteString("Configuration diagnostics:\n")
+	if d.MigrationStatus != "" {
+		fmt.Fprintf(&b, "  migration: %s\n", d.MigrationStatus)
+	}
+	for _, m := range d.MalformedFiles {
+		fmt.Fprintf(&b, "  malformed: %s\n", m)
+	}
+	for _, i := range d.IgnoredFiles {
+		fmt.Fprintf(&b, "  ignored: %s\n", i)
+	}
+	if d.ImportImported > 0 || d.ImportSkipped > 0 {
+		fmt.Fprintf(&b, "  import: %d imported, %d skipped\n", d.ImportImported, d.ImportSkipped)
+	}
+	for _, e := range d.ImportErrors {
+		fmt.Fprintf(&b, "  import error: %s\n", e)
+	}
+	return b.String()
+}
+
+func redactPath(p string) string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return p
+	}
+	if strings.HasPrefix(p, home) {
+		return "~" + p[len(home):]
+	}
+	return p
+}
diff --git a/internal/config/dotenv.go b/internal/config/dotenv.go
index 5acdb3f85..8ec90487f 100644
--- a/internal/config/dotenv.go
+++ b/internal/config/dotenv.go
@@ -7,26 +7,14 @@ import (
 	"strings"
 )
 
-// loadDotEnv loads KEY=value files into the process environment without
-// overriding variables that are already set (first file to set a key wins).
-// Order: a project ./.env (read-only back-compat, so a manual project override
-// takes precedence), then the reasonix-owned global credentials file in the user
-// config dir (where `reasonix setup` writes keys, so they resolve from any
-// directory without ever touching a project's own .env), then ~/.env as a legacy
-// fallback (the desktop app writes there). Existing environment variables always
-// win over all three.
+// loadDotEnv loads only global credentials and legacy ~/.env. Project .env is no
+// longer read, avoiding cwd-dependent API key or MCP env changes.
 func loadDotEnv() {
-	loadDotEnvForRoot(".")
+	loadDotEnvGlobal()
 }
 
-// loadDotEnvForRoot loads a root's .env file (if present) before the home .env
-// fallback. When root is "." it behaves like loadDotEnv().
-func loadDotEnvForRoot(root string) {
-	dotEnvPath := ".env"
-	if root != "" && root != "." {
-		dotEnvPath = filepath.Join(root, ".env")
-	}
-	loadDotEnvFile(dotEnvPath)
+// loadDotEnvGlobal loads the global credentials and legacy home .env only.
+func loadDotEnvGlobal() {
 	if p := UserCredentialsPath(); p != "" {
 		loadDotEnvFile(p)
 	}
diff --git a/internal/config/dotenv_test.go b/internal/config/dotenv_test.go
index b514d9da3..b68026bb4 100644
--- a/internal/config/dotenv_test.go
+++ b/internal/config/dotenv_test.go
@@ -6,59 +6,16 @@ import (
 	"testing"
 )
 
-// TestLoadDotEnvFallsBackToHome proves the unified-key behaviour: the working
-// directory's .env wins, but a key only present in ~/.env is still picked up —
-// so a key set once in the home .env (the desktop app writes there) reaches the
-// CLI run from any project directory. Existing env vars beat both files.
-func TestLoadDotEnvFallsBackToHome(t *testing.T) {
-	cwd := t.TempDir()
-	home := t.TempDir()
-
-	if err := os.WriteFile(filepath.Join(cwd, ".env"), []byte("KEY_CWD=from_cwd\nKEY_SHARED=cwd_wins\n"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(home, ".env"), []byte("KEY_HOME=from_home\nKEY_SHARED=home_loses\n"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-
-	t.Chdir(cwd)
-	t.Setenv("HOME", home)
-	t.Setenv("USERPROFILE", home) // os.UserHomeDir reads HOME on Unix and USERPROFILE on Windows.
-
-	// Start clean so the file values are what land (Setenv auto-restores).
-	t.Setenv("KEY_CWD", "")
-	os.Unsetenv("KEY_CWD")
-	t.Setenv("KEY_HOME", "")
-	os.Unsetenv("KEY_HOME")
-	t.Setenv("KEY_SHARED", "")
-	os.Unsetenv("KEY_SHARED")
-
-	loadDotEnv()
-
-	if got := os.Getenv("KEY_CWD"); got != "from_cwd" {
-		t.Errorf("cwd-only key not loaded: KEY_CWD=%q", got)
-	}
-	if got := os.Getenv("KEY_HOME"); got != "from_home" {
-		t.Errorf("~/.env fallback failed: KEY_HOME=%q want from_home", got)
-	}
-	if got := os.Getenv("KEY_SHARED"); got != "cwd_wins" {
-		t.Errorf("cwd .env should take precedence over ~/.env: KEY_SHARED=%q want cwd_wins", got)
-	}
-}
-
-// TestLoadDotEnvReadsGlobalCredentials proves `reasonix setup`'s target — the
-// reasonix-owned credentials file in the user config dir — is loaded from any
-// working directory, while a project ./.env still wins on a shared key.
 func TestLoadDotEnvReadsGlobalCredentials(t *testing.T) {
-	cwd := t.TempDir()
 	cfgHome := t.TempDir()
 
-	t.Chdir(cwd)
+	t.Chdir(t.TempDir())
 	t.Setenv("HOME", cfgHome)
 	t.Setenv("USERPROFILE", cfgHome)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(cfgHome, ".config"))
 	t.Setenv("AppData", filepath.Join(cfgHome, "AppData"))
 
+	// Write to the global credentials file
 	cred := UserCredentialsPath()
 	if cred == "" {
 		t.Skip("user config dir unresolved on this platform")
@@ -66,40 +23,44 @@ func TestLoadDotEnvReadsGlobalCredentials(t *testing.T) {
 	if err := os.MkdirAll(filepath.Dir(cred), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(cred, []byte("KEY_GLOBAL=from_credentials\nKEY_SHARED=global_loses\n"), 0o600); err != nil {
+	if err := os.WriteFile(cred, []byte("KEY_GLOBAL=from_credentials\n"), 0o600); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(cwd, ".env"), []byte("KEY_SHARED=cwd_wins\n"), 0o600); err != nil {
+	// Write legacy home .env
+	if err := os.WriteFile(filepath.Join(cfgHome, ".env"), []byte("KEY_HOME=from_home\n"), 0o600); err != nil {
 		t.Fatal(err)
 	}
 
 	t.Setenv("KEY_GLOBAL", "")
 	os.Unsetenv("KEY_GLOBAL")
-	t.Setenv("KEY_SHARED", "")
-	os.Unsetenv("KEY_SHARED")
+	t.Setenv("KEY_HOME", "")
+	os.Unsetenv("KEY_HOME")
 
 	loadDotEnv()
 
 	if got := os.Getenv("KEY_GLOBAL"); got != "from_credentials" {
 		t.Errorf("global credentials not loaded: KEY_GLOBAL=%q want from_credentials", got)
 	}
-	if got := os.Getenv("KEY_SHARED"); got != "cwd_wins" {
-		t.Errorf("project .env should win over global credentials: KEY_SHARED=%q want cwd_wins", got)
+	if got := os.Getenv("KEY_HOME"); got != "from_home" {
+		t.Errorf("home .env not loaded: KEY_HOME=%q want from_home", got)
 	}
 }
 
-// TestLoadDotEnvDoesNotOverrideEnv confirms an already-set environment variable
-// beats both .env files (the documented first-wins contract).
 func TestLoadDotEnvDoesNotOverrideEnv(t *testing.T) {
-	cwd := t.TempDir()
-	if err := os.WriteFile(filepath.Join(cwd, ".env"), []byte("PINNED=from_file\n"), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	t.Chdir(cwd)
 	home := t.TempDir()
 	t.Setenv("HOME", home)
 	t.Setenv("USERPROFILE", home)
 	t.Setenv("PINNED", "from_env")
+	t.Chdir(t.TempDir())
+
+	// Write to credentials to test env precedence
+	cred := UserCredentialsPath()
+	if cred != "" {
+		if err := os.MkdirAll(filepath.Dir(cred), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		os.WriteFile(cred, []byte("PINNED=from_file\n"), 0o600)
+	}
 
 	loadDotEnv()
 
diff --git a/internal/config/edit.go b/internal/config/edit.go
index ff4730665..5dbc19113 100644
--- a/internal/config/edit.go
+++ b/internal/config/edit.go
@@ -7,7 +7,6 @@ import (
 	"runtime"
 	"strings"
 
-	"reasonix/internal/fileutil"
 	"reasonix/internal/mcpdiag"
 	"reasonix/internal/netclient"
 	"reasonix/internal/permission"
@@ -398,6 +397,7 @@ func CanonicalSkillPath(path string) string {
 // position). The transport-specific required fields are validated: stdio needs
 // a command, http/sse need a url.
 func (c *Config) UpsertPlugin(e PluginEntry) error {
+	e, _ = NormalizePluginCommandLine(e)
 	if err := validatePlugin(e); err != nil {
 		return err
 	}
@@ -446,39 +446,51 @@ func (c *Config) ClearPluginAuthentication(name string) (PluginEntry, bool, erro
 // user config. Source priority mirrors Load(): project TOML, user TOML, then the
 // project .mcp.json entry if TOML did not define that server.
 func ClearPluginAuthenticationInSource(name string) (PluginEntry, bool, string, error) {
-	if path := pluginTOMLSourcePath(name); path != "" {
-		cfg := LoadForEdit(path)
-		updated, changed, err := cfg.ClearPluginAuthentication(name)
-		if err != nil {
-			return PluginEntry{}, false, path, err
-		}
-		if changed {
-			if err := cfg.SaveTo(path); err != nil {
-				return PluginEntry{}, false, path, err
+	// Check mcp.toml first — it is the sole MCP authority when it exists.
+	if mcpPath := UserMCPConfigPath(); mcpPath != "" {
+		if _, statErr := os.Stat(mcpPath); statErr == nil {
+			plugins, _ := loadMCPTOML()
+			for i := range plugins {
+				if plugins[i].Name != name {
+					continue
+				}
+				headers, env, url, changed := mcpdiag.ClearAuthConfig(plugins[i].Headers, plugins[i].Env, plugins[i].URL)
+				plugins[i].Headers = headers
+				plugins[i].Env = env
+				plugins[i].URL = url
+				if err := SaveMCPTOML(plugins); err != nil {
+					return PluginEntry{}, false, mcpPath, err
+				}
+				return plugins[i], changed, mcpPath, nil
 			}
 		}
-		return updated, changed, path, nil
-	}
-	updated, changed, err := clearMCPJSONAuthentication(mcpJSONFile, name)
-	if err != nil {
-		return PluginEntry{}, false, "", err
 	}
-	return updated, changed, mcpJSONFile, nil
-}
-
-func pluginTOMLSourcePath(name string) string {
-	for _, path := range []string{"reasonix.toml", userConfigPath()} {
-		if strings.TrimSpace(path) == "" {
-			continue
-		}
-		cfg := LoadForEdit(path)
-		for _, p := range cfg.Plugins {
-			if p.Name == name {
-				return path
+	// Fall back to global config.toml for pre-migration configs.
+	if uc := UserConfigPath(); strings.TrimSpace(uc) != "" {
+		if _, statErr := os.Stat(uc); statErr == nil {
+			cfg := LoadForEdit(uc)
+			for i := range cfg.Plugins {
+				if cfg.Plugins[i].Name == name {
+					updated, changed, err := cfg.ClearPluginAuthentication(name)
+					if err != nil {
+						return PluginEntry{}, false, uc, err
+					}
+					if changed {
+						if err := cfg.SaveTo(uc); err != nil {
+							return PluginEntry{}, false, uc, err
+						}
+					}
+					return updated, changed, uc, nil
+				}
 			}
 		}
 	}
-	return ""
+	// Fall back to project .mcp.json — still used as a manual import source.
+	updated, changed, err := clearMCPJSONAuthentication(mcpJSONFile, name)
+	if err == nil {
+		return updated, changed, mcpJSONFile, nil
+	}
+	return PluginEntry{}, false, "", fmt.Errorf("clear plugin authentication: no plugin %q", name)
 }
 
 // validatePlugin checks a plugin entry by transport. An empty Type means stdio.
@@ -525,8 +537,7 @@ func SaveMinimalProjectAutoPlan(path, mode string) (string, error) {
 	if err := cfg.SetAutoPlan(mode); err != nil {
 		return "", err
 	}
-	body := fmt.Sprintf(`# Reasonix project configuration.
-# Project-local overrides are merged over the user config.
+	body := fmt.Sprintf(`# Reasonix global configuration.
 
 [agent]
 auto_plan = %q
@@ -534,31 +545,6 @@ auto_plan = %q
 	return cfg.Agent.AutoPlan, writeConfigFile(path, body)
 }
 
-func writeConfigFile(path, body string) error {
-	if strings.TrimSpace(path) == "" {
-		return fmt.Errorf("save: empty config path")
-	}
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("save: create dir: %w", err)
-	}
-	tmp, err := os.CreateTemp(dir, ".reasonix.*.toml.tmp")
-	if err != nil {
-		return fmt.Errorf("save: create temp: %w", err)
-	}
-	tmpPath := tmp.Name()
-	if _, err := tmp.WriteString(body); err != nil {
-		tmp.Close()
-		os.Remove(tmpPath)
-		return fmt.Errorf("save: write: %w", err)
-	}
-	if err := tmp.Close(); err != nil {
-		os.Remove(tmpPath)
-		return fmt.Errorf("save: close temp: %w", err)
-	}
-	return fileutil.ReplaceFile(tmpPath, path)
-}
-
 func renderScopeForPath(path string) RenderScope {
 	if isUserConfigPath(path) {
 		return RenderScopeUser
@@ -568,7 +554,7 @@ func renderScopeForPath(path string) RenderScope {
 
 func isUserConfigPath(path string) bool {
 	path = strings.TrimSpace(path)
-	uc := strings.TrimSpace(userConfigPath())
+	uc := strings.TrimSpace(UserConfigPath())
 	if path == "" || uc == "" {
 		return false
 	}
@@ -580,33 +566,24 @@ func isUserConfigPath(path string) bool {
 	return filepath.Clean(path) == filepath.Clean(uc)
 }
 
-// Save writes the configuration back to the file it was loaded from
-// (SourcePath), or to ./reasonix.toml when none exists yet — the conventional
-// project-local target a fresh GUI session would create.
+// Save writes the configuration to the global config file.
 func (c *Config) Save() error {
-	path := SourcePath()
+	path := UserConfigPath()
 	if path == "" {
-		path = "reasonix.toml"
+		return fmt.Errorf("save: cannot resolve user config path")
 	}
 	return c.SaveTo(path)
 }
 
-// SaveForRoot saves the config to root's reasonix.toml, falling back to the
-// user's global config when root has no existing reasonix.toml.
+// SaveForRoot saves the config to the global config file (project layer removed).
 func (c *Config) SaveForRoot(root string) error {
-	root = resolveRoot(root)
-	projectTOML := "reasonix.toml"
-	if root != "." {
-		projectTOML = filepath.Join(root, "reasonix.toml")
-	}
-	if _, err := os.Stat(projectTOML); err == nil {
-		return c.SaveTo(projectTOML)
+	uc := UserConfigPath()
+	if uc == "" {
+		root := resolveRoot(root)
+		return c.SaveTo(filepath.Join(root, "reasonix.toml"))
 	}
-	if uc := userConfigPath(); uc != "" {
-		if err := os.MkdirAll(filepath.Dir(uc), 0o755); err != nil {
-			return err
-		}
-		return c.SaveTo(uc)
+	if err := os.MkdirAll(filepath.Dir(uc), 0o755); err != nil {
+		return err
 	}
-	return c.SaveTo(projectTOML)
+	return c.SaveTo(uc)
 }
diff --git a/internal/config/edit_test.go b/internal/config/edit_test.go
index 90dfcc0f0..64e4dbb6e 100644
--- a/internal/config/edit_test.go
+++ b/internal/config/edit_test.go
@@ -526,13 +526,13 @@ func TestLoadFirstRunDisablesCodegraph(t *testing.T) {
 	}
 }
 
-func TestPluginResolvedTierDefaultsToLazy(t *testing.T) {
+func TestPluginResolvedTierDefaultsToBackground(t *testing.T) {
 	for _, tc := range []struct {
 		name string
 		tier string
 		want string
 	}{
-		{name: "empty", tier: "", want: "lazy"},
+		{name: "empty", tier: "", want: "background"},
 		{name: "explicit lazy", tier: "lazy", want: "lazy"},
 		{name: "background", tier: "background", want: "background"},
 		{name: "eager", tier: "eager", want: "eager"},
@@ -648,11 +648,10 @@ func TestSaveToRoundTrips(t *testing.T) {
 	if got.Network.ProxyMode != "custom" || got.Network.Proxy.Server != "127.0.0.1" || got.Network.Proxy.Port != 7890 {
 		t.Errorf("network = %+v", got.Network)
 	}
-	if len(got.Plugins) != 1 || got.Plugins[0].Name != "stripe" {
-		t.Errorf("plugins = %+v", got.Plugins)
-	}
-	if got.Plugins[0].AutoStart == nil || *got.Plugins[0].AutoStart {
-		t.Errorf("auto_start should round-trip false, got %+v", got.Plugins[0].AutoStart)
+	// Plugins are no longer serialized into config.toml — they live in
+	// ~/.reasonix/mcp.toml. The round-trip through config.toml omits them.
+	if len(got.Plugins) != 0 {
+		t.Errorf("plugins = %+v, want empty (plugins now in mcp.toml)", got.Plugins)
 	}
 }
 
diff --git a/internal/config/loadedit_test.go b/internal/config/loadedit_test.go
index f36ac5469..96d928007 100644
--- a/internal/config/loadedit_test.go
+++ b/internal/config/loadedit_test.go
@@ -3,6 +3,7 @@ package config
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -36,3 +37,78 @@ api_key_env = "X_KEY"
 		t.Errorf("missing-file default = %q, want %q", cfg.DefaultModel, Default().DefaultModel)
 	}
 }
+
+func TestLoadForEditMigratesLegacyMCPTiers(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "reasonix.toml")
+	body := `
+[codegraph]
+enabled = true
+tier = "eager"
+
+[[plugins]]
+name = "playwright"
+command = "npx"
+tier = "lazy"
+
+[[providers]]
+name = "local"
+kind = "openai"
+base_url = "https://x"
+model = "m"
+`
+	if err := os.WriteFile(path, []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg := LoadForEdit(path)
+	if cfg.Codegraph.Tier != "" {
+		t.Fatalf("codegraph tier = %q, want migrated empty", cfg.Codegraph.Tier)
+	}
+	if len(cfg.Plugins) != 1 || cfg.Plugins[0].Tier != "" {
+		t.Fatalf("plugins after migration = %+v, want empty tier", cfg.Plugins)
+	}
+	updated, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(updated), "\ntier") {
+		t.Fatalf("legacy tier lines should be removed from file:\n%s", updated)
+	}
+	if !strings.Contains(string(updated), `command = "npx"`) || !strings.Contains(string(updated), `[codegraph]`) {
+		t.Fatalf("migration should preserve ordinary config:\n%s", updated)
+	}
+}
+
+func TestLoadMigratesLegacyMCPTiersFromMCPTOML(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	if err := os.MkdirAll(UserRootDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `
+[[plugins]]
+name = "github"
+command = "npx"
+tier = "lazy"
+`
+	if err := os.WriteFile(UserMCPConfigPath(), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cfg, err := Load()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(cfg.Plugins) != 1 || cfg.Plugins[0].Tier != "" {
+		t.Fatalf("plugins after migration = %+v, want empty tier", cfg.Plugins)
+	}
+	updated, err := os.ReadFile(UserMCPConfigPath())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(string(updated), "\ntier") {
+		t.Fatalf("legacy tier lines should be removed from mcp.toml:\n%s", updated)
+	}
+}
diff --git a/internal/config/mcp_command.go b/internal/config/mcp_command.go
new file mode 100644
index 000000000..1eb6ee506
--- /dev/null
+++ b/internal/config/mcp_command.go
@@ -0,0 +1,120 @@
+package config
+
+import (
+	"path/filepath"
+	"strings"
+	"unicode"
+)
+
+// NormalizePluginCommandLine repairs the common MCP copy/paste mistake where a
+// tutorial's full command line is placed in command while args is left empty.
+// Valid commands that are just paths with spaces are left untouched unless they
+// are quoted or start with a known MCP runner such as npx/uvx/node.
+func NormalizePluginCommandLine(e PluginEntry) (PluginEntry, bool) {
+	if pluginEntryTransport(e) != "stdio" || len(e.Args) > 0 {
+		e.Command = strings.TrimSpace(e.Command)
+		return e, false
+	}
+	cmd := strings.TrimSpace(e.Command)
+	e.Command = cmd
+	if !strings.ContainsAny(cmd, " \t\r\n") {
+		return e, false
+	}
+	parts, ok := splitPluginCommandLine(cmd)
+	if !ok || len(parts) < 2 || !shouldSplitPluginCommand(cmd, parts[0]) {
+		return e, false
+	}
+	e.Command = parts[0]
+	e.Args = parts[1:]
+	return e, true
+}
+
+func normalizePluginCommandLines(c *Config) {
+	if c == nil {
+		return
+	}
+	for i := range c.Plugins {
+		c.Plugins[i], _ = NormalizePluginCommandLine(c.Plugins[i])
+	}
+}
+
+func pluginEntryTransport(e PluginEntry) string {
+	switch strings.ToLower(strings.TrimSpace(e.Type)) {
+	case "", "stdio":
+		return "stdio"
+	case "http", "streamable-http":
+		return "http"
+	case "sse":
+		return "sse"
+	default:
+		return strings.ToLower(strings.TrimSpace(e.Type))
+	}
+}
+
+func shouldSplitPluginCommand(original, first string) bool {
+	trimmed := strings.TrimLeftFunc(original, unicode.IsSpace)
+	if strings.HasPrefix(trimmed, `"`) || strings.HasPrefix(trimmed, `'`) {
+		return true
+	}
+	return knownMCPCommandRunner(first)
+}
+
+func knownMCPCommandRunner(command string) bool {
+	base := commandBase(command)
+	base = strings.ToLower(base)
+	for _, ext := range []string{".exe", ".cmd", ".bat", ".ps1"} {
+		base = strings.TrimSuffix(base, ext)
+	}
+	switch base {
+	case "npx", "npm", "node", "pnpm", "yarn", "bun",
+		"uvx", "uv", "python", "python3", "py",
+		"docker", "deno", "go", "cmd", "powershell", "pwsh":
+		return true
+	default:
+		return false
+	}
+}
+
+func commandBase(command string) string {
+	command = strings.ReplaceAll(command, `\`, `/`)
+	return filepath.Base(command)
+}
+
+func splitPluginCommandLine(s string) ([]string, bool) {
+	var parts []string
+	var b strings.Builder
+	var quote rune
+	inToken := false
+	flush := func() {
+		if !inToken {
+			return
+		}
+		parts = append(parts, b.String())
+		b.Reset()
+		inToken = false
+	}
+	for _, r := range s {
+		if quote == 0 && unicode.IsSpace(r) {
+			flush()
+			continue
+		}
+		if r == '"' || r == '\'' {
+			switch quote {
+			case 0:
+				quote = r
+				inToken = true
+				continue
+			case r:
+				quote = 0
+				continue
+			}
+		}
+		inToken = true
+		b.WriteRune(r)
+	}
+	if quote != 0 {
+		return nil, false
+	}
+	flush()
+	return parts, true
+}
diff --git a/internal/config/mcp_toml.go b/internal/config/mcp_toml.go
new file mode 100644
index 000000000..b1946a372
--- /dev/null
+++ b/internal/config/mcp_toml.go
@@ -0,0 +1,135 @@
+package config
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/BurntSushi/toml"
+)
+
+// mcpTOMLTop mirrors the top-level structure of ~/.reasonix/mcp.toml.
+type mcpTOMLTop struct {
+	Plugins []PluginEntry `toml:"plugins"`
+}
+
+// loadMCPTOML reads ~/.reasonix/mcp.toml and returns its plugin entries.
+// An absent file returns nil, nil. Malformed entries are nonfatal: they are
+// skipped and individual errors are collected.
+func loadMCPTOML() ([]PluginEntry, error) {
+	path := UserMCPConfigPath()
+	if path == "" {
+		return nil, nil
+	}
+	if _, err := os.Stat(path); err != nil {
+		return nil, nil
+	}
+	var top mcpTOMLTop
+	if _, err := toml.DecodeFile(path, &top); err != nil {
+		return nil, fmt.Errorf("parse %s: %w", path, err)
+	}
+	// Validate entries, skipping bad ones.
+	var out []PluginEntry
+	var errs []string
+	for _, p := range top.Plugins {
+		if err := validatePlugin(p); err != nil {
+			errs = append(errs, fmt.Sprintf("plugin %q: %v", p.Name, err))
+			continue
+		}
+		out = append(out, p)
+	}
+	if len(errs) > 0 {
+		return out, fmt.Errorf("mcp.toml: %s", joinErrors(errs))
+	}
+	return out, nil
+}
+
+// SaveMCPTOML writes the plugin entries to ~/.reasonix/mcp.toml, creating a
+// timestamp backup first.
+func SaveMCPTOML(plugins []PluginEntry) error {
+	path := UserMCPConfigPath()
+	if path == "" {
+		return fmt.Errorf("save mcp: cannot resolve mcp config path")
+	}
+	content := RenderMCPTOML(plugins)
+	return writeConfigFile(path, content)
+}
+
+// RenderMCPTOML serializes plugin entries as annotated TOML.
+func RenderMCPTOML(plugins []PluginEntry) string {
+	var b string
+	b = "# MCP server configuration.\n"
+	b += "# These servers are shared across all Reasonix sessions.\n"
+	b += "# ${VAR} / ${VAR:-default} are expanded from the environment.\n\n"
+	for _, p := range plugins {
+		b += "\n[[plugins]]\n"
+		b += fmt.Sprintf("name    = %q\n", p.Name)
+		if p.Type != "" {
+			b += fmt.Sprintf("type    = %q\n", p.Type)
+		}
+		if p.Command != "" {
+			b += fmt.Sprintf("command = %q\n", p.Command)
+		}
+		if len(p.Args) > 0 {
+			b += fmt.Sprintf("args    = %s\n", renderStringArray(p.Args))
+		}
+		if p.URL != "" {
+			b += fmt.Sprintf("url     = %q\n", p.URL)
+		}
+		if len(p.Headers) > 0 {
+			b += fmt.Sprintf("headers = %s\n", renderStringMap(p.Headers))
+		}
+		if len(p.Env) > 0 {
+			b += fmt.Sprintf("env     = %s\n", renderStringMap(p.Env))
+		}
+		if p.AutoStart != nil {
+			b += fmt.Sprintf("auto_start = %v\n", *p.AutoStart)
+		}
+	}
+	return b
+}
+
+// UpsertMCPPlugin adds or replaces an MCP server and persists to mcp.toml.
+func UpsertMCPPlugin(e PluginEntry) error {
+	e.Tier = ""
+	plugins, _ := loadMCPTOML()
+	for i := range plugins {
+		if plugins[i].Name == e.Name {
+			plugins[i] = e
+			return SaveMCPTOML(plugins)
+		}
+	}
+	plugins = append(plugins, e)
+	return SaveMCPTOML(plugins)
+}
+
+// RemoveMCPPlugin deletes a named MCP server from mcp.toml.
+func RemoveMCPPlugin(name string) (bool, error) {
+	plugins, _ := loadMCPTOML()
+	for i := range plugins {
+		if plugins[i].Name == name {
+			plugins = append(plugins[:i], plugins[i+1:]...)
+			return true, SaveMCPTOML(plugins)
+		}
+	}
+	return false, nil
+}
+
+// ListMCPPlugins returns all MCP servers from mcp.toml.
+func ListMCPPlugins() ([]PluginEntry, error) {
+	plugins, err := loadMCPTOML()
+	if err != nil {
+		return nil, err
+	}
+	return plugins, nil
+}
+
+func joinErrors(errs []string) string {
+	if len(errs) == 0 {
+		return ""
+	}
+	s := errs[0]
+	for _, e := range errs[1:] {
+		s += "; " + e
+	}
+	return s
+}
diff --git a/internal/config/mcpjson.go b/internal/config/mcpjson.go
index 08e7c4db4..359fbad97 100644
--- a/internal/config/mcpjson.go
+++ b/internal/config/mcpjson.go
@@ -106,7 +106,7 @@ func loadLegacyMCP(path string) []PluginEntry {
 }
 
 func pluginEntryFromMCPSpec(name string, s mcpServerSpec) PluginEntry {
-	return PluginEntry{
+	e := PluginEntry{
 		Name:      name,
 		Type:      s.Type,
 		Command:   s.Command,
@@ -116,6 +116,8 @@ func pluginEntryFromMCPSpec(name string, s mcpServerSpec) PluginEntry {
 		Headers:   s.Headers,
 		AutoStart: s.AutoStart,
 	}
+	e, _ = NormalizePluginCommandLine(e)
+	return e
 }
 
 // mergeMCPJSON appends servers from .mcp.json that the TOML config did not
diff --git a/internal/config/mcpjson_test.go b/internal/config/mcpjson_test.go
index 717bb67f9..cb67755b6 100644
--- a/internal/config/mcpjson_test.go
+++ b/internal/config/mcpjson_test.go
@@ -32,7 +32,6 @@ func TestLoadMCPJSON(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	// Sorted by name: filesystem before stripe.
 	if len(got) != 2 || got[0].Name != "filesystem" || got[1].Name != "stripe" {
 		t.Fatalf("entries = %+v, want [filesystem stripe] sorted", got)
 	}
@@ -47,16 +46,85 @@ func TestLoadMCPJSON(t *testing.T) {
 	}
 }
 
+func TestNormalizePluginCommandLine(t *testing.T) {
+	cases := []struct {
+		name        string
+		in          PluginEntry
+		wantCommand string
+		wantArgs    []string
+		wantChanged bool
+	}{
+		{
+			name:        "npx pasted with args",
+			in:          PluginEntry{Name: "playwright", Command: "npx -y @playwright/mcp"},
+			wantCommand: "npx",
+			wantArgs:    []string{"-y", "@playwright/mcp"},
+			wantChanged: true,
+		},
+		{
+			name:        "quoted command path",
+			in:          PluginEntry{Name: "quoted", Command: `"C:\Program Files\nodejs\npx.cmd" -y @example/mcp`},
+			wantCommand: `C:\Program Files\nodejs\npx.cmd`,
+			wantArgs:    []string{"-y", "@example/mcp"},
+			wantChanged: true,
+		},
+		{
+			name:        "empty quoted arg preserved",
+			in:          PluginEntry{Name: "empty", Command: `npx --token "" @example/mcp`},
+			wantCommand: "npx",
+			wantArgs:    []string{"--token", "", "@example/mcp"},
+			wantChanged: true,
+		},
+		{
+			name:        "unquoted command path with spaces stays literal",
+			in:          PluginEntry{Name: "literal", Command: `C:\Program Files\nodejs\npx.cmd`},
+			wantCommand: `C:\Program Files\nodejs\npx.cmd`,
+			wantChanged: false,
+		},
+		{
+			name:        "remote entry untouched",
+			in:          PluginEntry{Name: "remote", Type: "http", URL: "https://mcp.example.com/mcp", Command: "npx -y nope"},
+			wantCommand: "npx -y nope",
+			wantChanged: false,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got, changed := NormalizePluginCommandLine(tc.in)
+			if changed != tc.wantChanged {
+				t.Fatalf("changed = %v, want %v", changed, tc.wantChanged)
+			}
+			if got.Command != tc.wantCommand {
+				t.Fatalf("command = %q, want %q", got.Command, tc.wantCommand)
+			}
+			if strings.Join(got.Args, "\x00") != strings.Join(tc.wantArgs, "\x00") {
+				t.Fatalf("args = %v, want %v", got.Args, tc.wantArgs)
+			}
+		})
+	}
+}
+
+func TestUpsertPluginNormalizesPastedCommandLine(t *testing.T) {
+	cfg := &Config{}
+	if err := cfg.UpsertPlugin(PluginEntry{Name: "playwright", Command: "npx -y @playwright/mcp"}); err != nil {
+		t.Fatal(err)
+	}
+	if got := cfg.Plugins[0].Command; got != "npx" {
+		t.Fatalf("command = %q, want npx", got)
+	}
+	if got := cfg.Plugins[0].Args; len(got) != 2 || got[0] != "-y" || got[1] != "@playwright/mcp" {
+		t.Fatalf("args = %v, want [-y @playwright/mcp]", got)
+	}
+}
+
 func TestLoadMCPJSONAbsentAndMalformed(t *testing.T) {
 	dir := t.TempDir()
 
-	// Absent file: not an error, no entries.
 	got, err := loadMCPJSON(filepath.Join(dir, "missing.json"))
 	if err != nil || got != nil {
 		t.Errorf("absent file: got (%v, %v), want (nil, nil)", got, err)
 	}
 
-	// Malformed file: an error so a typo surfaces instead of dropping servers.
 	bad := filepath.Join(dir, mcpJSONFile)
 	if err := os.WriteFile(bad, []byte("{not json"), 0o644); err != nil {
 		t.Fatal(err)
@@ -66,25 +134,30 @@ func TestLoadMCPJSONAbsentAndMalformed(t *testing.T) {
 	}
 }
 
-func TestLoadMergesMCPJSON(t *testing.T) {
-	// Point the user-config and home dirs at an empty temp dir so Load picks up
-	// no global config, then chdir into a project dir holding both files.
-	empty := t.TempDir()
-	t.Setenv("HOME", empty)
-	t.Setenv("XDG_CONFIG_HOME", empty)
+func TestLoadOnlyUsesGlobalConfig(t *testing.T) {
+	// Project reasonix.toml is no longer read.
+	root := t.TempDir()
+	t.Setenv("HOME", root)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(root, "xdg"))
+	t.Setenv("AppData", filepath.Join(root, "AppData"))
 	t.Chdir(t.TempDir())
 
-	toml := `[[plugins]]
-name = "shared"
-command = "local-bin"
-`
-	if err := os.WriteFile("reasonix.toml", []byte(toml), 0o644); err != nil {
+	gpath := UserConfigPath()
+	if gpath == "" {
+		t.Fatal("UserConfigPath empty under isolated env")
+	}
+	if err := os.MkdirAll(filepath.Dir(gpath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(gpath, []byte("[[plugins]]\nname = \"globalmcp\"\ncommand = \"global-bin\"\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	mcp := `{ "mcpServers": {
-  "shared": { "type": "http", "url": "https://override.example" },
-  "extra":  { "command": "extra-bin", "auto_start": false }
-} }`
+	// Write a project reasonix.toml — it should be ignored.
+	if err := os.WriteFile("reasonix.toml", []byte("[[plugins]]\nname = \"projectmcp\"\ncommand = \"project-bin\"\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	// Write .mcp.json — it should also be ignored.
+	mcp := `{ "mcpServers": { "extra": { "command": "extra-bin" } } }`
 	if err := os.WriteFile(mcpJSONFile, []byte(mcp), 0o644); err != nil {
 		t.Fatal(err)
 	}
@@ -93,62 +166,57 @@ command = "local-bin"
 	if err != nil {
 		t.Fatal(err)
 	}
-	byName := map[string]PluginEntry{}
+	// Only globalmcp should appear (from global config). Project and .mcp.json are ignored.
 	for _, p := range cfg.Plugins {
-		byName[p.Name] = p
-	}
-	if len(byName) != 2 {
-		t.Fatalf("plugins = %+v, want shared + extra", cfg.Plugins)
-	}
-	if byName["shared"].Command != "local-bin" || byName["shared"].URL != "" {
-		t.Errorf("reasonix.toml should win the collision, got %+v", byName["shared"])
-	}
-	if byName["extra"].Command != "extra-bin" {
-		t.Errorf("extra not merged from .mcp.json, got %+v", byName["extra"])
+		if p.Name == "projectmcp" {
+			t.Error("project reasonix.toml [[plugins]] should be ignored")
+		}
+		if p.Name == "extra" {
+			t.Error(".mcp.json should not be auto-loaded")
+		}
+	}
+	found := false
+	for _, p := range cfg.Plugins {
+		if p.Name == "globalmcp" {
+			found = true
+		}
 	}
-	if byName["extra"].AutoStart == nil || *byName["extra"].AutoStart {
-		t.Errorf("extra auto_start=false not preserved, got %+v", byName["extra"].AutoStart)
+	if !found {
+		t.Error("global [[plugins]] not loaded")
 	}
 }
 
-func TestLoadMergesPluginsAcrossTOMLSources(t *testing.T) {
-	root := t.TempDir()
-	t.Setenv("HOME", root)
-	t.Setenv("XDG_CONFIG_HOME", filepath.Join(root, "xdg"))
-	t.Setenv("AppData", filepath.Join(root, "AppData")) // os.UserConfigDir reads AppData on Windows
+func TestLoadNormalizesTOMLPastedCommandLine(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, "xdg"))
+	t.Setenv("AppData", filepath.Join(home, "AppData"))
+	t.Setenv("APPDATA", filepath.Join(home, "AppData"))
 	t.Chdir(t.TempDir())
 
-	gpath := UserConfigPath()
-	if gpath == "" {
-		t.Fatal("UserConfigPath empty under isolated env")
-	}
-	if err := os.MkdirAll(filepath.Dir(gpath), 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Join(home, ".reasonix"), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(gpath, []byte("[[plugins]]\nname = \"globalmcp\"\ncommand = \"global-bin\"\n"), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(home, ".reasonix", "mcp.toml"), []byte("[[plugins]]\nname = \"playwright\"\ncommand = \"npx -y @playwright/mcp\"\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile("reasonix.toml", []byte("[[plugins]]\nname = \"projectmcp\"\ncommand = \"project-bin\"\n"), 0o644); err != nil {
-		t.Fatal(err)
-	}
-
 	cfg, err := Load()
 	if err != nil {
 		t.Fatal(err)
 	}
-	names := map[string]bool{}
-	for _, p := range cfg.Plugins {
-		names[p.Name] = true
+	if len(cfg.Plugins) != 1 {
+		t.Fatalf("plugins = %+v", cfg.Plugins)
 	}
-	if !names["globalmcp"] || !names["projectmcp"] {
-		t.Fatalf("a project reasonix.toml [[plugins]] dropped the global config's server; got %+v", cfg.Plugins)
+	if cfg.Plugins[0].Command != "npx" {
+		t.Fatalf("command = %q, want npx", cfg.Plugins[0].Command)
+	}
+	if got := cfg.Plugins[0].Args; len(got) != 2 || got[0] != "-y" || got[1] != "@playwright/mcp" {
+		t.Fatalf("args = %v, want [-y @playwright/mcp]", got)
 	}
 }
 
 func TestMergeMCPJSONPrecedence(t *testing.T) {
-	// reasonix.toml already declares "shared" (stdio); .mcp.json offers a colliding
-	// "shared" (http) plus a fresh "extra". reasonix.toml must win on the collision;
-	// "extra" gets appended.
 	cfg := &Config{Plugins: []PluginEntry{
 		{Name: "shared", Command: "local-bin"},
 	}}
@@ -175,11 +243,12 @@ func TestClearPluginAuthenticationInSourceUsesMCPJSON(t *testing.T) {
 	t.Setenv("AppData", filepath.Join(root, "AppData"))
 	t.Chdir(t.TempDir())
 
+	// Global config should not have the server
 	userPath := UserConfigPath()
 	if err := os.MkdirAll(filepath.Dir(userPath), 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(userPath, []byte("[[plugins]]\nname = \"global\"\ncommand = \"global-bin\"\n"), 0o644); err != nil {
+	if err := os.WriteFile(userPath, []byte(""), 0o644); err != nil {
 		t.Fatal(err)
 	}
 	mcp := `{
@@ -210,13 +279,6 @@ func TestClearPluginAuthenticationInSourceUsesMCPJSON(t *testing.T) {
 		t.Fatalf("updated URL = %q", updated.URL)
 	}
 
-	userRaw, err := os.ReadFile(userPath)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(string(userRaw), "dida") {
-		t.Fatalf("user config should not receive .mcp.json server:\n%s", userRaw)
-	}
 	entries, err := loadMCPJSON(mcpJSONFile)
 	if err != nil {
 		t.Fatal(err)
@@ -242,14 +304,18 @@ func TestClearPluginAuthenticationInSourceUsesMCPJSON(t *testing.T) {
 	}
 }
 
-func TestClearPluginAuthenticationInSourcePrefersTOML(t *testing.T) {
+func TestClearPluginAuthenticationInSourcePrefersGlobalConfig(t *testing.T) {
 	root := t.TempDir()
 	t.Setenv("HOME", root)
 	t.Setenv("XDG_CONFIG_HOME", filepath.Join(root, "xdg"))
 	t.Setenv("AppData", filepath.Join(root, "AppData"))
 	t.Chdir(t.TempDir())
 
-	if err := os.WriteFile("reasonix.toml", []byte(`[[plugins]]
+	gpath := UserConfigPath()
+	if err := os.MkdirAll(filepath.Dir(gpath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(gpath, []byte(`[[plugins]]
 name = "dida"
 type = "http"
 url = "https://reasonix.example/mcp?access_token=toml"
@@ -258,16 +324,6 @@ Authorization = "Bearer ${TOML_TOKEN}"
 `), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	mcp := `{ "mcpServers": {
-  "dida": {
-    "type": "http",
-    "url": "https://mcp-json.example/mcp?access_token=json",
-    "headers": { "Authorization": "Bearer ${JSON_TOKEN}" }
-  }
-} }`
-	if err := os.WriteFile(mcpJSONFile, []byte(mcp), 0o644); err != nil {
-		t.Fatal(err)
-	}
 
 	updated, changed, source, err := ClearPluginAuthenticationInSource("dida")
 	if err != nil {
@@ -276,26 +332,19 @@ Authorization = "Bearer ${TOML_TOKEN}"
 	if !changed {
 		t.Fatal("ClearPluginAuthenticationInSource should report changed")
 	}
-	if source != "reasonix.toml" {
-		t.Fatalf("source = %q, want reasonix.toml", source)
+	if source != gpath {
+		t.Fatalf("source = %q, want %q", source, gpath)
 	}
 	if updated.URL != "https://reasonix.example/mcp" {
 		t.Fatalf("updated URL = %q", updated.URL)
 	}
 
-	projectRaw, err := os.ReadFile("reasonix.toml")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(string(projectRaw), "access_token=toml") || strings.Contains(string(projectRaw), "Authorization") {
-		t.Fatalf("reasonix.toml auth material should be removed:\n%s", projectRaw)
-	}
-	mcpRaw, err := os.ReadFile(mcpJSONFile)
+	globalRaw, err := os.ReadFile(gpath)
 	if err != nil {
 		t.Fatal(err)
 	}
-	if !strings.Contains(string(mcpRaw), "access_token=json") {
-		t.Fatalf(".mcp.json collision entry should be left untouched:\n%s", mcpRaw)
+	if strings.Contains(string(globalRaw), "access_token=toml") || strings.Contains(string(globalRaw), "Authorization") {
+		t.Fatalf("global config auth material should be removed:\n%s", globalRaw)
 	}
 }
 
@@ -316,7 +365,6 @@ func TestLoadLegacyMCP(t *testing.T) {
 	}
 
 	got := loadLegacyMCP(path)
-	// "old" is in mcpDisabled and dropped; github + remote remain, name-sorted.
 	if len(got) != 2 {
 		t.Fatalf("got %d entries, want 2: %+v", len(got), got)
 	}
@@ -330,8 +378,6 @@ func TestLoadLegacyMCP(t *testing.T) {
 		t.Errorf("remote mapped wrong: %+v", got[1])
 	}
 
-	// Absent, malformed, and empty paths must not error — just yield nil, so a
-	// stale legacy file can never block startup.
 	if got := loadLegacyMCP(filepath.Join(dir, "nope.json")); got != nil {
 		t.Errorf("absent file: got %+v, want nil", got)
 	}
diff --git a/internal/config/migrate.go b/internal/config/migrate.go
index fe4960005..4827b8d1d 100644
--- a/internal/config/migrate.go
+++ b/internal/config/migrate.go
@@ -8,12 +8,13 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"time"
+
+	"github.com/BurntSushi/toml"
 )
 
 // legacyConfig is the subset of the v0.x (~/.reasonix/config.json) schema this
-// import carries forward. Fields absent here are dropped on purpose: desktop tab
-// state is frontend-owned, and skills already live in the shared ~/.reasonix/skills
-// root that v1+ also scans, so they need no migration.
+// import carries forward.
 type legacyConfig struct {
 	APIKey      string                       `json:"apiKey"`
 	BaseURL     string                       `json:"baseUrl"`
@@ -36,21 +37,22 @@ type legacyMCPServer struct {
 
 // MigrationResult summarizes a one-time legacy import for the boot-time notice.
 type MigrationResult struct {
-	From     string
-	To       string
-	KeyToEnv bool
-	Plugins  int
-	Warnings []string
+	From        string
+	To          string
+	KeyToEnv    bool
+	Plugins     int
+	Warnings    []string
+	SourceFiles []string
 }
 
 func (r *MigrationResult) Notice() string {
 	var b strings.Builder
-	fmt.Fprintf(&b, "migrated your previous configuration: %s → %s", r.From, r.To)
+	fmt.Fprintf(&b, "migrated your previous configuration to %s", r.To)
 	if r.Plugins > 0 {
 		fmt.Fprintf(&b, " (%d MCP server(s))", r.Plugins)
 	}
 	if r.KeyToEnv {
-		b.WriteString("; API key saved to reasonix's credentials store")
+		b.WriteString("; API key saved to credentials")
 	}
 	b.WriteString(". The old files were left untouched.")
 	for _, w := range r.Warnings {
@@ -60,15 +62,14 @@ func (r *MigrationResult) Notice() string {
 }
 
 // MigrateLegacyIfNeeded performs a one-time, non-destructive import of older
-// installs into the current user config when the latter does not exist yet. It
-// checks v1-era TOML first, then v0.5/v0.x ~/.reasonix/config.json, and never
-// modifies or deletes the legacy files. Returns nil when there is nothing to
-// migrate, or when the current user config already exists.
+// installs into the new ~/.reasonix layout. Checks for existing config first,
+// then migrates from old XDG/macOS Library/Windows AppData directories.
 func MigrateLegacyIfNeeded() (*MigrationResult, error) {
-	dest := userConfigPath()
+	dest := UserConfigPath()
 	if dest == "" {
 		return nil, nil
 	}
+	// Already migrated: ~/.reasonix/config.toml exists.
 	if _, err := os.Stat(dest); err == nil {
 		return nil, nil
 	}
@@ -76,16 +77,18 @@ func MigrateLegacyIfNeeded() (*MigrationResult, error) {
 	if err != nil {
 		return nil, nil
 	}
-	if res, err := migrateLegacyTOMLIfNeeded(dest, home); res != nil || err != nil {
+	// Check old XDG / platform-specific config directories for an existing config.
+	if res, err := migrateOldConfigToNew(dest, home); res != nil || err != nil {
 		return res, err
 	}
+	// v0.x ~/.reasonix/config.json
 	src := filepath.Join(home, ".reasonix", "config.json")
 	data, err := os.ReadFile(src)
 	if err != nil {
 		return nil, nil
 	}
 	var legacy legacyConfig
-	data = bytes.TrimPrefix(data, []byte{0xEF, 0xBB, 0xBF}) // tolerate a UTF-8 BOM (some editors add one)
+	data = bytes.TrimPrefix(data, []byte{0xEF, 0xBB, 0xBF})
 	if err := json.Unmarshal(data, &legacy); err != nil {
 		return nil, fmt.Errorf("parse legacy config %s: %w", src, err)
 	}
@@ -97,8 +100,8 @@ func MigrateLegacyIfNeeded() (*MigrationResult, error) {
 		_ = cfg.SetDesktopLanguage(legacy.Lang)
 	}
 	migrateLegacyBaseURL(cfg, legacy.BaseURL)
-	cfg.Plugins = legacyPlugins(legacy)
-	res.Plugins = len(cfg.Plugins)
+	mcpPlugins := legacyPlugins(legacy)
+	res.Plugins = len(mcpPlugins)
 
 	var envLines []string
 	if key := strings.TrimSpace(legacy.APIKey); key != "" {
@@ -116,21 +119,34 @@ func MigrateLegacyIfNeeded() (*MigrationResult, error) {
 	if err := cfg.WriteFile(dest); err != nil {
 		return nil, fmt.Errorf("write %s: %w", dest, err)
 	}
+	// Write MCP to separate mcp.toml
+	if len(mcpPlugins) > 0 {
+		if err := SaveMCPTOML(mcpPlugins); err != nil {
+			res.Warnings = append(res.Warnings, "could not write mcp.toml: "+err.Error())
+		}
+	}
 	if len(envLines) > 0 {
 		if err := writeCredentialsEnv(home, envLines); err != nil {
 			return res, fmt.Errorf("write credentials: %w", err)
 		}
 	}
+	// Copy sessions, archive, memory from old ~/.reasonix to new root
+	migrateDataDirs(filepath.Join(home, ".reasonix"), UserRootDir(), res)
+	writeMigrationRecord(res)
 	return res, nil
 }
 
-func migrateLegacyTOMLIfNeeded(dest, home string) (*MigrationResult, error) {
-	for _, src := range legacyTOMLPaths(dest, home) {
-		if src == "" || filepath.Clean(src) == filepath.Clean(dest) {
-			continue
-		}
+// migrateOldConfigToNew checks old platform-specific config directories and migrates
+// the config to the new ~/.reasonix layout, splitting into config/mcp/skills.
+func migrateOldConfigToNew(dest, home string) (*MigrationResult, error) {
+	for _, oldRoot := range oldLegacyPaths() {
+		src := filepath.Join(oldRoot, "config.toml")
 		if _, err := os.Stat(src); err != nil {
-			continue
+			// Also check the old filename: reasonix.toml in the same dirs
+			src = filepath.Join(oldRoot, "reasonix.toml")
+			if _, err := os.Stat(src); err != nil {
+				continue
+			}
 		}
 		cfg := Default()
 		if err := mergeFile(cfg, src); err != nil {
@@ -140,23 +156,237 @@ func migrateLegacyTOMLIfNeeded(dest, home string) (*MigrationResult, error) {
 		if strings.TrimSpace(cfg.Desktop.CloseBehavior) == "" && strings.TrimSpace(cfg.UI.CloseBehavior) != "" {
 			cfg.Desktop.CloseBehavior = cfg.DesktopCloseBehavior()
 		}
+
+		// Split: core stays in config.toml, plugins → mcp.toml, skills → skills.toml
+		mcpPlugins := cfg.Plugins
+		cfg.Plugins = nil // remove from core config
+
 		if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {
 			return nil, fmt.Errorf("create config dir: %w", err)
 		}
 		if err := cfg.WriteFile(dest); err != nil {
 			return nil, fmt.Errorf("write %s: %w", dest, err)
 		}
-		return &MigrationResult{From: src, To: dest, Plugins: len(cfg.Plugins)}, nil
+		if len(mcpPlugins) > 0 {
+			if err := SaveMCPTOML(mcpPlugins); err != nil {
+				return nil, fmt.Errorf("write mcp.toml: %w", err)
+			}
+		}
+		if err := SaveSkillsTOML(cfg); err != nil {
+			return nil, fmt.Errorf("write skills.toml: %w", err)
+		}
+
+		// Copy data dirs
+		migrateDataDirs(oldRoot, UserRootDir(), nil)
+		writeMigrationRecord(&MigrationResult{From: src, To: dest, Plugins: len(mcpPlugins)})
+		return &MigrationResult{From: src, To: dest, Plugins: len(mcpPlugins)}, nil
 	}
 	return nil, nil
 }
 
-func legacyTOMLPaths(dest, home string) []string {
-	paths := []string{filepath.Join(filepath.Dir(dest), "reasonix.toml")}
-	if home != "" {
-		paths = append(paths, filepath.Join(home, ".reasonix", "reasonix.toml"))
+// migrateDataDirs copies sessions, archive, and memory from oldRoot to newRoot
+// if the old data exists and the new does not.
+func migrateDataDirs(oldRoot, newRoot string, res *MigrationResult) {
+	if oldRoot == "" || newRoot == "" || filepath.Clean(oldRoot) == filepath.Clean(newRoot) {
+		return
+	}
+	subdirs := []string{"sessions", "archive", "memory"}
+	for _, sub := range subdirs {
+		oldDir := filepath.Join(oldRoot, sub)
+		newDir := filepath.Join(newRoot, sub)
+		if _, err := os.Stat(oldDir); os.IsNotExist(err) {
+			continue
+		}
+		if _, err := os.Stat(newDir); err == nil {
+			continue // already has data
+		}
+		if err := copyDir(oldDir, newDir); err != nil {
+			if res != nil {
+				res.Warnings = append(res.Warnings, fmt.Sprintf("could not copy %s: %v", sub, err))
+			}
+		}
+	}
+}
+
+func copyDir(src, dst string) error {
+	if err := os.MkdirAll(dst, 0o755); err != nil {
+		return err
+	}
+	entries, err := os.ReadDir(src)
+	if err != nil {
+		return err
+	}
+	for _, e := range entries {
+		srcPath := filepath.Join(src, e.Name())
+		dstPath := filepath.Join(dst, e.Name())
+		if e.IsDir() {
+			if err := copyDir(srcPath, dstPath); err != nil {
+				return err
+			}
+			continue
+		}
+		data, err := os.ReadFile(srcPath)
+		if err != nil {
+			continue
+		}
+		if err := os.WriteFile(dstPath, data, 0o644); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// writeMigrationRecord writes a migration.json to ~/.reasonix recording the event.
+func writeMigrationRecord(r *MigrationResult) {
+	if r == nil {
+		return
+	}
+	record := map[string]any{
+		"from":    r.From,
+		"to":      r.To,
+		"time":    time.Now().UTC().Format(time.RFC3339),
+		"plugins": r.Plugins,
+	}
+	if len(r.Warnings) > 0 {
+		record["warnings"] = r.Warnings
+	}
+	data, err := json.MarshalIndent(record, "", "  ")
+	if err != nil {
+		return
+	}
+	path := MigrationPath()
+	if path != "" {
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			return
+		}
+		_ = os.WriteFile(path, append(data, '\n'), 0o644)
+	}
+}
+
+// ImportConfigFromPath imports a legacy config file (TOML or .mcp.json) into the
+// global config. Returns counts and errors.
+func ImportConfigFromPath(srcPath string) (imported, skipped int, errors []string) {
+	if _, err := os.Stat(srcPath); os.IsNotExist(err) {
+		errors = append(errors, fmt.Sprintf("file not found: %s", srcPath))
+		return
+	}
+	ext := strings.ToLower(filepath.Ext(srcPath))
+	switch ext {
+	case ".toml":
+		return importTOMLSource(srcPath)
+	case ".json":
+		return importJSONSource(srcPath)
+	default:
+		errors = append(errors, fmt.Sprintf("unsupported file type: %s (expected .toml or .json)", srcPath))
+	}
+	return
+}
+
+func importTOMLSource(srcPath string) (imported, skipped int, errors []string) {
+	src := Default()
+	if err := mergeFile(src, srcPath); err != nil {
+		errors = append(errors, err.Error())
+		return
+	}
+	hasSkills, err := tomlSourceDeclaresSkills(srcPath)
+	if err != nil {
+		errors = append(errors, err.Error())
+		return
+	}
+	// MCP: skip name conflicts — existing global entry wins.
+	existing, _ := loadMCPTOML()
+	have := map[string]bool{}
+	for _, p := range existing {
+		have[p.Name] = true
+	}
+	for _, p := range src.Plugins {
+		if have[p.Name] {
+			skipped++
+			continue
+		}
+		if err := UpsertMCPPlugin(p); err != nil {
+			errors = append(errors, fmt.Sprintf("plugin %q: %v", p.Name, err))
+			skipped++
+		} else {
+			have[p.Name] = true
+			imported++
+		}
+	}
+	if !hasSkills {
+		return
+	}
+	// Skills: merge into existing skills.toml content.
+	current, err := loadExistingSkillsForImport()
+	if err != nil {
+		errors = append(errors, err.Error())
+		return
+	}
+	for _, p := range src.Skills.Paths {
+		if err := current.AddSkillPath(p); err != nil {
+			errors = append(errors, fmt.Sprintf("skill path %q: %v", p, err))
+			skipped++
+		}
+	}
+	for _, name := range src.Skills.DisabledSkills {
+		if err := current.SetSkillEnabled(name, false); err != nil {
+			errors = append(errors, fmt.Sprintf("disabled skill %q: %v", name, err))
+			skipped++
+		}
+	}
+	if err := SaveSkillsTOML(current); err != nil {
+		errors = append(errors, fmt.Sprintf("skills.toml: %v", err))
+	}
+	return
+}
+
+func tomlSourceDeclaresSkills(path string) (bool, error) {
+	var raw map[string]any
+	if _, err := toml.DecodeFile(path, &raw); err != nil {
+		return false, err
+	}
+	_, ok := raw["skills"]
+	return ok, nil
+}
+
+func loadExistingSkillsForImport() (*Config, error) {
+	cfg := Default()
+	if path := UserConfigPath(); strings.TrimSpace(path) != "" {
+		if err := mergeFile(cfg, path); err != nil {
+			return cfg, err
+		}
+	}
+	if err := loadSkillsTOML(cfg); err != nil {
+		return cfg, err
+	}
+	return cfg, nil
+}
+
+func importJSONSource(srcPath string) (imported, skipped int, errors []string) {
+	entries, err := loadMCPJSON(srcPath)
+	if err != nil {
+		errors = append(errors, err.Error())
+		return
+	}
+	// Check for existing names — skip conflicts, don't overwrite.
+	existing, _ := loadMCPTOML()
+	have := map[string]bool{}
+	for _, p := range existing {
+		have[p.Name] = true
+	}
+	for _, e := range entries {
+		if have[e.Name] {
+			skipped++
+			continue
+		}
+		if err := UpsertMCPPlugin(e); err != nil {
+			errors = append(errors, fmt.Sprintf("plugin %q: %v", e.Name, err))
+			skipped++
+		} else {
+			have[e.Name] = true
+			imported++
+		}
 	}
-	return paths
+	return
 }
 
 func migrateLegacyBaseURL(cfg *Config, baseURL string) {
@@ -200,13 +430,12 @@ func legacyPlugins(legacy legacyConfig) []PluginEntry {
 			off := false
 			pe.AutoStart = &off
 		}
+		pe, _ = NormalizePluginCommandLine(pe)
 		out = append(out, pe)
 	}
 	return out
 }
 
-// normalizeTransport maps the v0.x transport names to v1+ plugin types. stdio is
-// the default, so it returns "" (RenderTOML then omits the field).
 func normalizeTransport(t string) string {
 	switch strings.ToLower(strings.TrimSpace(t)) {
 	case "http", "streamable-http":
@@ -225,8 +454,6 @@ func firstNonEmpty(a, b string) string {
 	return b
 }
 
-// mergeEnv overlays the per-server env map onto the spec's own env (overlay wins,
-// matching v0.x mcpEnv precedence). Returns nil when both are empty.
 func mergeEnv(base, overlay map[string]string) map[string]string {
 	if len(base) == 0 && len(overlay) == 0 {
 		return nil
@@ -241,12 +468,6 @@ func mergeEnv(base, overlay map[string]string) map[string]string {
 	return out
 }
 
-// writeCredentialsEnv merges lines into the reasonix-owned global credentials
-// file (UserCredentialsPath, e.g. %AppData%\reasonix\credentials), replacing any
-// existing assignment of the same key, and pins them into the current process env
-// so the just-built session resolves the key without a restart. Falls back to
-// ~/.env only when the user config dir can't be resolved — never a project .env,
-// so a migration keeps secrets out of the user's project tree.
 func writeCredentialsEnv(home string, lines []string) error {
 	path := UserCredentialsPath()
 	if path == "" {
diff --git a/internal/config/migrate_test.go b/internal/config/migrate_test.go
index 61008544a..0bc397c4f 100644
--- a/internal/config/migrate_test.go
+++ b/internal/config/migrate_test.go
@@ -7,16 +7,14 @@ import (
 	"testing"
 )
 
-// legacyHome points HOME / config-dir / .env resolution at a fresh temp tree and
-// returns the legacy config.json path and the v1+ dest config path.
 func legacyHome(t *testing.T) (src, dest, home string) {
 	t.Helper()
 	home = t.TempDir()
 	t.Setenv("HOME", home)
-	t.Setenv("USERPROFILE", home)                               // os.UserHomeDir on Windows
-	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config")) // os.UserConfigDir on Linux
-	t.Setenv("AppData", filepath.Join(home, "AppData"))         // os.UserConfigDir on Windows
-	return filepath.Join(home, ".reasonix", "config.json"), userConfigPath(), home
+	t.Setenv("USERPROFILE", home)
+	t.Setenv("XDG_CONFIG_HOME", filepath.Join(home, ".config"))
+	t.Setenv("AppData", filepath.Join(home, "AppData"))
+	return filepath.Join(home, ".reasonix", "config.json"), UserConfigPath(), home
 }
 
 func writeLegacy(t *testing.T, src, body string) {
@@ -63,16 +61,30 @@ func TestMigrateImportsKeyPluginsAndLang(t *testing.T) {
 		t.Errorf("migration must not write the user's ~/.env, stat err=%v", err)
 	}
 
+	// Core config should have language but NOT plugins (they are in mcp.toml now)
 	got, err := os.ReadFile(dest)
 	if err != nil {
 		t.Fatalf("read dest config: %v", err)
 	}
 	toml := string(got)
-	for _, want := range []string{`language      = "zh"`, `[desktop]`, `language = "zh"`, `name    = "fs"`, `name    = "stripe"`, `type    = "http"`, `auto_start = false`} {
+	for _, want := range []string{`language      = "zh"`, `[desktop]`, `language = "zh"`} {
 		if !strings.Contains(toml, want) {
 			t.Errorf("dest config missing %q:\n%s", want, toml)
 		}
 	}
+	// Plugins should NOT be in config.toml
+	// Check mcp.toml has the plugins (not config.toml)
+
+	mcpData, err := os.ReadFile(UserMCPConfigPath())
+	if err != nil {
+		t.Fatalf("read mcp.toml: %v", err)
+	}
+	mcpToml := string(mcpData)
+	for _, want := range []string{`name    = "fs"`, `name    = "stripe"`, `type    = "http"`, `auto_start = false`} {
+		if !strings.Contains(mcpToml, want) {
+			t.Errorf("mcp.toml missing %q:\n%s", want, mcpToml)
+		}
+	}
 
 	if _, err := os.Stat(src); err != nil {
 		t.Errorf("legacy file must be left untouched: %v", err)
@@ -118,8 +130,8 @@ func TestMigrateSkipsWhenDestExists(t *testing.T) {
 }
 
 func TestMigrateImportsLegacyV1TOMLBeforeJSON(t *testing.T) {
-	srcJSON, dest, _ := legacyHome(t)
-	legacyTOML := filepath.Join(filepath.Dir(dest), "reasonix.toml")
+	srcJSON, _, _ := legacyHome(t)
+	legacyTOML := filepath.Join(filepath.Dir(UserConfigPath()), "reasonix.toml")
 	if err := os.MkdirAll(filepath.Dir(legacyTOML), 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -148,23 +160,28 @@ command = "legacy-bin"
 		t.Fatalf("expected v1 TOML migration, got %+v", res)
 	}
 
-	got, err := os.ReadFile(dest)
+	got, err := os.ReadFile(UserConfigPath())
 	if err != nil {
 		t.Fatalf("read migrated config: %v", err)
 	}
 	text := string(got)
-	for _, want := range []string{`config_version = 2`, `[desktop]`, `close_behavior = "quit"`, `name    = "legacy-v1"`} {
+	for _, want := range []string{`config_version = 2`, `[desktop]`, `close_behavior = "quit"`} {
 		if !strings.Contains(text, want) {
 			t.Fatalf("migrated TOML missing %q:\n%s", want, text)
 		}
 	}
+	// Plugins migrated to mcp.toml, not in config.toml as real entries
+	mcpData, _ := os.ReadFile(UserMCPConfigPath())
+	if !strings.Contains(string(mcpData), `name    = "legacy-v1"`) {
+		t.Fatal("mcp.toml missing plugin:\n" + string(mcpData))
+	}
 	if _, err := os.Stat(UserCredentialsPath()); !os.IsNotExist(err) {
 		t.Fatalf("v1 TOML migration should not import lower-priority JSON key, credentials stat err=%v", err)
 	}
 }
 
 func TestMigrateImportsLegacyV1HomeTOMLBeforeJSON(t *testing.T) {
-	srcJSON, dest, home := legacyHome(t)
+	srcJSON, _, home := legacyHome(t)
 	legacyTOML := filepath.Join(home, ".reasonix", "reasonix.toml")
 	if err := os.MkdirAll(filepath.Dir(legacyTOML), 0o755); err != nil {
 		t.Fatal(err)
@@ -188,16 +205,12 @@ command = "legacy-home-bin"
 		t.Fatalf("expected home v1 TOML migration, got %+v", res)
 	}
 
-	got, err := os.ReadFile(dest)
-	if err != nil {
-		t.Fatalf("read migrated config: %v", err)
-	}
-	text := string(got)
-	if !strings.Contains(text, `name    = "legacy-home-v1"`) {
-		t.Fatalf("home v1 plugin was not migrated:\n%s", text)
+	mcpData, _ := os.ReadFile(UserMCPConfigPath())
+	if !strings.Contains(string(mcpData), `name    = "legacy-home-v1"`) {
+		t.Fatal("home v1 plugin was not migrated to mcp.toml:\n" + string(mcpData))
 	}
-	if strings.Contains(text, `name    = "json"`) {
-		t.Fatalf("lower-priority v0.5 JSON should not be merged when v1 TOML exists:\n%s", text)
+	if strings.Contains(string(mcpData), `name    = "json"`) {
+		t.Fatalf("lower-priority v0.5 JSON should not be merged when v1 TOML exists:\n%s", mcpData)
 	}
 }
 
@@ -209,9 +222,98 @@ func TestMigrateNoLegacyIsNoop(t *testing.T) {
 	}
 }
 
+func TestImportTOMLWithoutSkillsPreservesInlineGlobalSkills(t *testing.T) {
+	_, _, home := legacyHome(t)
+	if err := os.MkdirAll(UserRootDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(UserConfigPath(), []byte(`
+default_model = "deepseek-flash"
+
+[skills]
+paths = ["~/inline-skills"]
+disabled_skills = ["review"]
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	src := filepath.Join(home, "project.toml")
+	if err := os.WriteFile(src, []byte(`
+[[plugins]]
+name = "imported"
+command = "imported-bin"
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	imported, skipped, errs := ImportConfigFromPath(src)
+	if len(errs) > 0 {
+		t.Fatalf("import errors: %v", errs)
+	}
+	if imported != 1 || skipped != 0 {
+		t.Fatalf("imported=%d skipped=%d, want 1/0", imported, skipped)
+	}
+	if _, err := os.Stat(UserSkillsConfigPath()); !os.IsNotExist(err) {
+		t.Fatalf("import without [skills] should not create skills.toml, stat err=%v", err)
+	}
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	if len(cfg.Skills.Paths) != 1 || cfg.Skills.Paths[0] != "~/inline-skills" {
+		t.Fatalf("inline skills paths were not preserved: %+v", cfg.Skills.Paths)
+	}
+	if len(cfg.Skills.DisabledSkills) != 1 || cfg.Skills.DisabledSkills[0] != "review" {
+		t.Fatalf("inline disabled skills were not preserved: %+v", cfg.Skills.DisabledSkills)
+	}
+}
+
+func TestImportTOMLWithSkillsMergesExistingInlineGlobalSkills(t *testing.T) {
+	_, _, home := legacyHome(t)
+	if err := os.MkdirAll(UserRootDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(UserConfigPath(), []byte(`
+default_model = "deepseek-flash"
+
+[skills]
+paths = ["~/inline-skills"]
+disabled_skills = ["review"]
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	src := filepath.Join(home, "project.toml")
+	if err := os.WriteFile(src, []byte(`
+[skills]
+paths = ["~/imported-skills"]
+disabled_skills = ["explore"]
+`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	if _, _, errs := ImportConfigFromPath(src); len(errs) > 0 {
+		t.Fatalf("import errors: %v", errs)
+	}
+	cfg, err := Load()
+	if err != nil {
+		t.Fatalf("load: %v", err)
+	}
+	paths := strings.Join(cfg.Skills.Paths, "\n")
+	for _, want := range []string{"~/inline-skills", "~/imported-skills"} {
+		if !strings.Contains(paths, want) {
+			t.Fatalf("merged skills paths missing %q: %+v", want, cfg.Skills.Paths)
+		}
+	}
+	disabled := strings.Join(cfg.Skills.DisabledSkills, "\n")
+	for _, want := range []string{"review", "explore"} {
+		if !strings.Contains(disabled, want) {
+			t.Fatalf("merged disabled skills missing %q: %+v", want, cfg.Skills.DisabledSkills)
+		}
+	}
+}
+
 func TestMigrateToleratesUTF8BOM(t *testing.T) {
 	src, _, _ := legacyHome(t)
-	writeLegacy(t, src, "\ufeff"+`{"apiKey":"sk-bom"}`)
+	writeLegacy(t, src, string([]byte{0xEF, 0xBB, 0xBF})+`{"apiKey":"sk-bom"}`)
 	res, err := MigrateLegacyIfNeeded()
 	if err != nil {
 		t.Fatalf("a BOM-prefixed legacy config must still parse: %v", err)
diff --git a/internal/config/paths.go b/internal/config/paths.go
new file mode 100644
index 000000000..d82d4f904
--- /dev/null
+++ b/internal/config/paths.go
@@ -0,0 +1,133 @@
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+)
+
+// UserRootDir returns the Reasonix user config root: ~/.reasonix on macOS/Linux,
+// %USERPROFILE%\.reasonix on Windows.
+func UserRootDir() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(home, ".reasonix")
+}
+
+// UserConfigPath returns the global config file: ~/.reasonix/config.toml.
+func UserConfigPath() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "config.toml")
+}
+
+// UserMCPConfigPath returns the global MCP config file: ~/.reasonix/mcp.toml.
+func UserMCPConfigPath() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "mcp.toml")
+}
+
+// UserSkillsConfigPath returns the global skills config file: ~/.reasonix/skills.toml.
+func UserSkillsConfigPath() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "skills.toml")
+}
+
+// UserCredentialsPath returns the global credentials file: ~/.reasonix/credentials,
+// falling back to the XDG-based path for compatibility.
+func UserCredentialsPath() string {
+	root := UserRootDir()
+	if root != "" {
+		return filepath.Join(root, "credentials")
+	}
+	dir, err := os.UserConfigDir()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(dir, "reasonix", "credentials")
+}
+
+// ArchiveDir returns the archive directory: ~/.reasonix/archive.
+func ArchiveDir() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "archive")
+}
+
+// SessionDir returns the session directory: ~/.reasonix/sessions.
+func SessionDir() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "sessions")
+}
+
+// CacheDir returns the cache directory: ~/.reasonix/cache.
+func CacheDir() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "cache")
+}
+
+// MemoryUserDir returns the user config root for memory: ~/.reasonix.
+func MemoryUserDir() string {
+	return UserRootDir()
+}
+
+// MigrationPath returns the migration record path: ~/.reasonix/migration.json.
+func MigrationPath() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "migration.json")
+}
+
+// BackupDir returns the config backup directory: ~/.reasonix/backups/config.
+func BackupDir() string {
+	root := UserRootDir()
+	if root == "" {
+		return ""
+	}
+	return filepath.Join(root, "backups", "config")
+}
+
+// oldLegacyPaths returns known historical Reasonix config directories for migration.
+func oldLegacyPaths() []string {
+	var paths []string
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return nil
+	}
+	switch runtime.GOOS {
+	case "darwin":
+		paths = append(paths, filepath.Join(home, "Library", "Application Support", "reasonix"))
+	case "windows":
+		if appData := os.Getenv("APPDATA"); appData != "" {
+			paths = append(paths, filepath.Join(appData, "reasonix"))
+		}
+	default:
+		if xdg := os.Getenv("XDG_CONFIG_HOME"); xdg != "" {
+			paths = append(paths, filepath.Join(xdg, "reasonix"))
+		} else {
+			paths = append(paths, filepath.Join(home, ".config", "reasonix"))
+		}
+	}
+	paths = append(paths, filepath.Join(home, ".reasonix"))
+	return paths
+}
diff --git a/internal/config/render.go b/internal/config/render.go
index 7384a28f3..2bb573c77 100644
--- a/internal/config/render.go
+++ b/internal/config/render.go
@@ -40,7 +40,7 @@ func RenderTOMLForScope(c *Config, scope RenderScope) string {
 	var b strings.Builder
 
 	b.WriteString("# Reasonix configuration.\n")
-	b.WriteString("# Resolution order: flag > ./reasonix.toml > ~/.config/reasonix/config.toml > built-in defaults.\n")
+	b.WriteString("# Resolution order: flag > ~/.reasonix/config.toml > built-in defaults.\n")
 	b.WriteString("# Secrets come from the environment via api_key_env; never put keys here.\n\n")
 
 	fmt.Fprintf(&b, "config_version = %d   # schema marker for diagnostics; old versions may ignore it\n", configVersion(c))
@@ -171,6 +171,16 @@ func RenderTOMLForScope(c *Config, scope RenderScope) string {
 	} else {
 		b.WriteString("# subagent_models = { review = \"deepseek-pro\", security_review = \"deepseek-pro\" }   # per-skill overrides\n")
 	}
+	if c.Agent.SubagentEffort != "" {
+		fmt.Fprintf(&b, "subagent_effort = %q   # default effort for subagent entry points\n", c.Agent.SubagentEffort)
+	} else {
+		b.WriteString("# subagent_effort = \"high\"   # optional default effort for subagents\n")
+	}
+	if len(c.Agent.SubagentEfforts) > 0 {
+		fmt.Fprintf(&b, "subagent_efforts = %s   # per-tool/skill effort overrides\n", renderStringMap(c.Agent.SubagentEfforts))
+	} else {
+		b.WriteString("# subagent_efforts = { review = \"max\", task = \"high\" }   # per-tool/skill effort overrides\n")
+	}
 	if c.Agent.OutputStyle != "" {
 		fmt.Fprintf(&b, "output_style = %q   # persona/tone folded into the prompt\n", c.Agent.OutputStyle)
 	} else {
@@ -247,24 +257,9 @@ func RenderTOMLForScope(c *Config, scope RenderScope) string {
 	} else {
 		b.WriteString("# path       = \"\"   # empty = cache, then PATH, then a bundle beside reasonix\n")
 	}
-	if strings.TrimSpace(c.Codegraph.Tier) != "" {
-		fmt.Fprintf(&b, "tier         = %q   # lazy|background|eager\n", c.Codegraph.ResolvedTier())
-	} else {
-		b.WriteString("# tier       = \"lazy\"   # lazy|background|eager\n")
-	}
 	b.WriteString("\n")
 
-	b.WriteString("[skills]\n")
-	if len(c.Skills.Paths) > 0 {
-		fmt.Fprintf(&b, "paths = %s   # extra custom skill roots\n", renderStringArray(c.Skills.Paths))
-	} else {
-		b.WriteString("# paths = [\"~/my-skills\", \"../shared/skills\"]   # extra custom skill roots\n")
-	}
-	if disabled := c.DisabledSkillNames(); len(disabled) > 0 {
-		fmt.Fprintf(&b, "disabled_skills = %s   # hidden from the prompt, slash invocation, and skill tools\n\n", renderStringArray(disabled))
-	} else {
-		b.WriteString("# disabled_skills = [\"review\"]   # hide noisy or unwanted skills\n\n")
-	}
+	b.WriteString("# Skills are managed in ~/.reasonix/skills.toml — see `reasonix config doctor`.\n\n")
 
 	b.WriteString("[permissions]\n")
 	b.WriteString("# Per-call gating. mode = writer fallback when no rule matches: ask|allow|deny.\n")
@@ -309,47 +304,7 @@ func RenderTOMLForScope(c *Config, scope RenderScope) string {
 	}
 	b.WriteString("\n")
 
-	b.WriteString("# External MCP servers. type: \"stdio\" (default, a subprocess) | \"http\" | \"sse\".\n")
-	b.WriteString("# ${VAR} / ${VAR:-default} are expanded from the environment in command/args/env/url/headers.\n")
-	if len(c.Plugins) == 0 {
-		b.WriteString("# [[plugins]]\n")
-		b.WriteString("# name    = \"example\"\n")
-		b.WriteString("# command = \"reasonix-plugin-example\"\n")
-		b.WriteString("# [[plugins]]                                  # a remote server over Streamable HTTP\n")
-		b.WriteString("# name    = \"stripe\"\n")
-		b.WriteString("# type    = \"http\"\n")
-		b.WriteString("# url     = \"https://mcp.stripe.com\"\n")
-		b.WriteString("# headers = { Authorization = \"Bearer ${STRIPE_KEY}\" }\n")
-	} else {
-		for _, pl := range c.Plugins {
-			b.WriteString("\n[[plugins]]\n")
-			fmt.Fprintf(&b, "name    = %q\n", pl.Name)
-			if pl.Type != "" {
-				fmt.Fprintf(&b, "type    = %q\n", pl.Type)
-			}
-			if pl.Command != "" {
-				fmt.Fprintf(&b, "command = %q\n", pl.Command)
-			}
-			if len(pl.Args) > 0 {
-				fmt.Fprintf(&b, "args    = %s\n", renderStringArray(pl.Args))
-			}
-			if pl.URL != "" {
-				fmt.Fprintf(&b, "url     = %q\n", pl.URL)
-			}
-			if len(pl.Headers) > 0 {
-				fmt.Fprintf(&b, "headers = %s\n", renderStringMap(pl.Headers))
-			}
-			if len(pl.Env) > 0 {
-				fmt.Fprintf(&b, "env     = %s\n", renderStringMap(pl.Env))
-			}
-			if pl.AutoStart != nil {
-				fmt.Fprintf(&b, "auto_start = %v\n", *pl.AutoStart)
-			}
-			if strings.TrimSpace(pl.Tier) != "" {
-				fmt.Fprintf(&b, "tier    = %q\n", pl.Tier)
-			}
-		}
-	}
+	b.WriteString("# MCP servers are managed in ~/.reasonix/mcp.toml — use `reasonix mcp` commands.\n")
 
 	return b.String()
 }
diff --git a/internal/config/render_test.go b/internal/config/render_test.go
index 7250a88de..5bb5e0566 100644
--- a/internal/config/render_test.go
+++ b/internal/config/render_test.go
@@ -40,6 +40,7 @@ func TestRenderTOMLRoundTrips(t *testing.T) {
 	}
 	orig.Skills.Paths = []string{"~/my-skills", "../shared/skills"}
 	orig.Skills.DisabledSkills = []string{"review", "explore"}
+	orig.Skills.MaxDepth = 2
 	orig.Codegraph = CodegraphConfig{Enabled: true, AutoInstall: false, Path: "/opt/codegraph", Tier: "background"}
 	orig.Plugins = []PluginEntry{
 		{Name: "example", Command: "reasonix-plugin-example"},
@@ -117,8 +118,8 @@ func TestRenderTOMLRoundTrips(t *testing.T) {
 	if got.Codegraph.Path != "/opt/codegraph" {
 		t.Errorf("codegraph.path = %q, want /opt/codegraph", got.Codegraph.Path)
 	}
-	if got.Codegraph.Tier != "background" {
-		t.Errorf("codegraph.tier = %q, want background", got.Codegraph.Tier)
+	if got.Codegraph.Tier != "" {
+		t.Errorf("codegraph.tier = %q, want migrated empty", got.Codegraph.Tier)
 	}
 	if got.Agent.SubagentModel != "mimo-pro" {
 		t.Errorf("subagent_model = %q, want mimo-pro", got.Agent.SubagentModel)
@@ -147,27 +148,19 @@ func TestRenderTOMLRoundTrips(t *testing.T) {
 	if got.Network.ProxyMode != "custom" || got.Network.Proxy.Type != "socks5" || got.Network.Proxy.Port != 7890 {
 		t.Errorf("network proxy not preserved: %+v", got.Network)
 	}
-	if len(got.Skills.Paths) != 2 || got.Skills.Paths[0] != "~/my-skills" {
-		t.Errorf("skills.paths = %v", got.Skills.Paths)
+	// Skills and plugins are no longer serialized into config.toml —
+	// they live in ~/.reasonix/skills.toml and ~/.reasonix/mcp.toml.
+	if len(got.Skills.Paths) != 0 {
+		t.Errorf("skills.paths should be empty in config.toml (now in skills.toml): %v", got.Skills.Paths)
 	}
-	if len(got.Skills.DisabledSkills) != 2 || got.Skills.DisabledSkills[0] != "review" || got.Skills.DisabledSkills[1] != "explore" {
-		t.Errorf("skills.disabled_skills = %v", got.Skills.DisabledSkills)
+	if len(got.Skills.DisabledSkills) != 0 {
+		t.Errorf("skills.disabled_skills should be empty in config.toml (now in skills.toml): %v", got.Skills.DisabledSkills)
 	}
-	if len(got.Plugins) != 2 {
-		t.Fatalf("plugins count = %d, want 2", len(got.Plugins))
+	if len(got.Plugins) != 0 {
+		t.Fatalf("plugins count = %d, want 0 (plugins now in mcp.toml)", len(got.Plugins))
 	}
-	stripe := got.Plugins[1]
-	if stripe.Name != "stripe" || stripe.Type != "http" || stripe.URL != "https://mcp.stripe.com" {
-		t.Errorf("http plugin not preserved: %+v", stripe)
-	}
-	if stripe.Headers["Authorization"] != "Bearer x" {
-		t.Errorf("plugin headers not preserved: %v", stripe.Headers)
-	}
-	if stripe.AutoStart == nil || *stripe.AutoStart {
-		t.Errorf("auto_start should render and parse as false, got %+v", stripe.AutoStart)
-	}
-	if stripe.Tier != "background" {
-		t.Errorf("plugin tier should render and parse as background, got %q", stripe.Tier)
+	if strings.Contains(rendered, "\ntier") {
+		t.Errorf("rendered config should not contain MCP tier fields:\n%s", rendered)
 	}
 }
 
diff --git a/internal/config/skills_toml.go b/internal/config/skills_toml.go
new file mode 100644
index 000000000..f15f54c7c
--- /dev/null
+++ b/internal/config/skills_toml.go
@@ -0,0 +1,62 @@
+package config
+
+import (
+	"os"
+
+	"github.com/BurntSushi/toml"
+)
+
+// skillsTOMLTop mirrors the top-level structure of ~/.reasonix/skills.toml.
+type skillsTOMLTop struct {
+	Skills SkillsConfig `toml:"skills"`
+}
+
+// loadSkillsTOML reads ~/.reasonix/skills.toml and replaces cfg.Skills
+// entirely — inline [skills] from config.toml is ignored when the file exists.
+// An absent file is not an error.
+func loadSkillsTOML(cfg *Config) error {
+	path := UserSkillsConfigPath()
+	if path == "" {
+		return nil
+	}
+	if _, err := os.Stat(path); err != nil {
+		return nil
+	}
+	var top skillsTOMLTop
+	if _, err := toml.DecodeFile(path, &top); err != nil {
+		return err
+	}
+	// Replace entirely: skills.toml is the sole authority.
+	cfg.Skills = top.Skills
+	return nil
+}
+
+// SaveSkillsTOML writes the skills config to ~/.reasonix/skills.toml.
+func SaveSkillsTOML(cfg *Config) error {
+	path := UserSkillsConfigPath()
+	if path == "" {
+		return nil
+	}
+	content := RenderSkillsTOML(cfg)
+	return writeConfigFile(path, content)
+}
+
+// RenderSkillsTOML serializes skills config as annotated TOML.
+func RenderSkillsTOML(cfg *Config) string {
+	var b string
+	b = "# Skills configuration.\n"
+	b += "# Paths: extra custom skill roots scanned globally.\n"
+	b += "# DisabledSkills: named skills hidden from the prompt and slash invocation.\n\n"
+	b += "[skills]\n"
+	if len(cfg.Skills.Paths) > 0 {
+		b += "paths = " + renderStringArray(cfg.Skills.Paths) + "\n"
+	} else {
+		b += "# paths = [\"~/my-skills\"]\n"
+	}
+	if disabled := cfg.DisabledSkillNames(); len(disabled) > 0 {
+		b += "disabled_skills = " + renderStringArray(disabled) + "\n"
+	} else {
+		b += "# disabled_skills = [\"review\"]\n"
+	}
+	return b
+}
diff --git a/internal/config/subagent_model_test.go b/internal/config/subagent_model_test.go
index 32ddf688d..13ac7c9db 100644
--- a/internal/config/subagent_model_test.go
+++ b/internal/config/subagent_model_test.go
@@ -25,4 +25,31 @@ subagent_models = { explore = "deepseek-pro", "security-review" = "mimo-pro" }
 	if cfg.Agent.SubagentModels["security-review"] != "mimo-pro" {
 		t.Fatalf("security-review model = %q", cfg.Agent.SubagentModels["security-review"])
 	}
+	if cfg.Agent.SubagentEffort != "" {
+		t.Fatalf("subagent_effort should be empty by default, got %q", cfg.Agent.SubagentEffort)
+	}
+	if len(cfg.Agent.SubagentEfforts) != 0 {
+		t.Fatalf("subagent_efforts should be empty by default, got %v", cfg.Agent.SubagentEfforts)
+	}
+}
+
+func TestAgentSubagentEffortConfigDecodesFromTOML(t *testing.T) {
+	var cfg Config
+	if _, err := toml.Decode(`
+	[agent]
+	subagent_effort = "max"
+	subagent_efforts = { review = "max", task = "high" }
+	`, &cfg); err != nil {
+		t.Fatalf("decode: %v", err)
+	}
+
+	if cfg.Agent.SubagentEffort != "max" {
+		t.Fatalf("subagent_effort = %q, want max", cfg.Agent.SubagentEffort)
+	}
+	if cfg.Agent.SubagentEfforts["review"] != "max" {
+		t.Fatalf("review effort = %q", cfg.Agent.SubagentEfforts["review"])
+	}
+	if cfg.Agent.SubagentEfforts["task"] != "high" {
+		t.Fatalf("task effort = %q", cfg.Agent.SubagentEfforts["task"])
+	}
 }
diff --git a/internal/control/controller.go b/internal/control/controller.go
index 04bf36e8b..88e0a12c2 100644
--- a/internal/control/controller.go
+++ b/internal/control/controller.go
@@ -1448,15 +1448,8 @@ func (c *Controller) AddMCPServer(e config.PluginEntry) (int, error) {
 	if err != nil {
 		return 0, err
 	}
-	cfg, lerr := config.Load()
-	if lerr != nil {
-		return n, fmt.Errorf("connected, but reloading config to save failed: %w", lerr)
-	}
-	if err := cfg.UpsertPlugin(e); err != nil {
-		return n, fmt.Errorf("connected, but config rejected the entry: %w", err)
-	}
-	if err := cfg.Save(); err != nil {
-		return n, fmt.Errorf("connected, but saving config failed: %w", err)
+	if err := config.UpsertMCPPlugin(e); err != nil {
+		return n, fmt.Errorf("connected, but saving to mcp.toml failed: %w", err)
 	}
 	return n, nil
 }
@@ -1591,20 +1584,16 @@ func (c *Controller) RemoveMCPServer(name string) (disconnected bool, err error)
 			}
 		}
 	}
-	cfg, lerr := config.Load()
-	if lerr != nil {
-		return disconnected, lerr
-	}
-	inConfig := cfg.RemovePlugin(name)
-	if inConfig {
+	found, rerr := config.RemoveMCPPlugin(name)
+	if found {
 		if !disconnected && c.reg != nil {
 			c.reg.RemovePrefix(plugin.ToolPrefix(name))
 		}
-		if serr := cfg.Save(); serr != nil {
-			return disconnected, serr
+		if rerr != nil {
+			return disconnected, rerr
 		}
 	}
-	if !disconnected && !inConfig {
+	if !disconnected && !found {
 		return false, fmt.Errorf("no MCP server named %q", name)
 	}
 	return disconnected, nil
diff --git a/internal/control/controller_test.go b/internal/control/controller_test.go
index 5062a44ab..b0796ad64 100644
--- a/internal/control/controller_test.go
+++ b/internal/control/controller_test.go
@@ -151,15 +151,22 @@ func TestDisconnectMCPServerRemovesLazyPlaceholder(t *testing.T) {
 }
 
 func TestRemoveMCPServerRemovesUnconnectedLazyPlaceholder(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
 	dir := t.TempDir()
 	t.Chdir(dir)
-	if err := os.WriteFile("reasonix.toml", []byte(`
+	mcpPath := filepath.Join(home, ".reasonix", "mcp.toml")
+	if err := os.MkdirAll(filepath.Dir(mcpPath), 0o755); err != nil {
+		t.Fatalf("create dir: %v", err)
+	}
+	if err := os.WriteFile(mcpPath, []byte(`
 [[plugins]]
 name = "mock"
 command = "mock-mcp"
 tier = "lazy"
 `), 0o644); err != nil {
-		t.Fatalf("write config: %v", err)
+		t.Fatalf("write mcp.toml: %v", err)
 	}
 
 	reg := tool.NewRegistry()
diff --git a/internal/doctor/report.go b/internal/doctor/report.go
index bbe61a4a8..9f3c10b17 100644
--- a/internal/doctor/report.go
+++ b/internal/doctor/report.go
@@ -125,7 +125,7 @@ func Collect(opts Options) Report {
 		Arch:    runtime.GOARCH,
 		CWD:     redactHome(cwd),
 		Config: ConfigReport{
-			SourcePath:   redactHome(config.SourcePath()),
+			SourcePath:   redactHome(config.UserConfigPath()),
 			UserPath:     redactHome(config.UserConfigPath()),
 			DefaultModel: cfg.DefaultModel,
 		},
diff --git a/internal/event/event.go b/internal/event/event.go
index 6c11177f6..7073d2aa8 100644
--- a/internal/event/event.go
+++ b/internal/event/event.go
@@ -89,6 +89,12 @@ const (
 	LevelWarn
 )
 
+// Profile carries the subagent model/effort resolved for this call.
+type Profile struct {
+	Model  string
+	Effort string
+}
+
 // Tool describes a tool call for ToolDispatch / ToolResult events. On dispatch
 // only ID/Name/Args/ReadOnly are set; on result Output/Err/Truncated are filled
 // in. Args is the raw JSON arguments — a sink compacts it for display.
@@ -109,6 +115,7 @@ type Tool struct {
 	// them under it. Empty for top-level calls.
 	ParentID string
 	FileDiff
+	Profile *Profile // ToolDispatch: subagent model/effort (set for task/skill calls)
 }
 
 // FileDiff is a previewed change carried on a writer tool's full ToolDispatch
diff --git a/internal/i18n/messages_en.go b/internal/i18n/messages_en.go
index 3fce398e2..9426a539b 100644
--- a/internal/i18n/messages_en.go
+++ b/internal/i18n/messages_en.go
@@ -308,7 +308,7 @@ Usage:
   reasonix chat [--model NAME] [-c|--continue] [--resume]   interactive session (multi-turn; -c resumes the latest, --resume picks one)
   reasonix run  [--model NAME] [--max-steps N] <task>   run one task and exit
   reasonix serve [--model NAME] [--addr HOST:PORT]      serve the session over HTTP+SSE (browser client at /)
-  reasonix setup [path]                                 interactive config wizard; writes reasonix.toml (+ .env)
+  reasonix setup                                        interactive config wizard; writes ~/.reasonix/config.toml (+ credentials)
   reasonix config auto-plan [off|on]                    configure automatic plan mode
   reasonix mcp <add|remove|list>                        manage MCP servers in reasonix.toml
   reasonix doctor [--json]                              print redacted local diagnostics
diff --git a/internal/i18n/messages_zh.go b/internal/i18n/messages_zh.go
index ceaf0f210..c61176293 100644
--- a/internal/i18n/messages_zh.go
+++ b/internal/i18n/messages_zh.go
@@ -309,7 +309,7 @@ var Chinese = Messages{
   reasonix chat [--model NAME] [-c|--continue] [--resume]   交互式会话（多轮；-c 恢复最近一次，--resume 选择一个）
   reasonix run  [--model NAME] [--max-steps N] <task>   执行单次任务后退出
   reasonix serve [--model NAME] [--addr HOST:PORT]      通过 HTTP+SSE 提供会话（浏览器客户端在 /）
-  reasonix setup [path]                                 交互式配置向导；生成 reasonix.toml（及 .env）
+  reasonix setup                                        交互式配置向导；生成 ~/.reasonix/config.toml（及 credentials）
   reasonix config auto-plan [off|on]                    配置自动计划模式
   reasonix mcp <add|remove|list>                        管理 reasonix.toml 里的 MCP 服务器
   reasonix doctor [--json]                              输出脱敏的本地诊断信息
diff --git a/internal/installsource/apply.go b/internal/installsource/apply.go
new file mode 100644
index 000000000..1f5e9ff16
--- /dev/null
+++ b/internal/installsource/apply.go
@@ -0,0 +1,348 @@
+package installsource
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"reasonix/internal/config"
+	"reasonix/internal/skill"
+)
+
+// apply dispatches to the per-action implementation. Each branch is
+// responsible for setting act.Status / act.Error / act.Next and for
+// cleaning up any partial side effects it left behind.
+func (t *installSourceTool) apply(ctx context.Context, req request, act *action) error {
+	switch act.Kind {
+	case "skill":
+		switch act.Action {
+		case "register_skill_root":
+			return t.applySkillRoot(req, act)
+		case "copy_skill":
+			return t.applyCopySkill(req, act)
+		case "link_skill":
+			return t.applyLinkSkill(req, act)
+		case "remove_skill":
+			return t.applyRemoveSkill(req, act)
+		case "remove_skill_root":
+			return t.applyRemoveSkillRoot(req, act)
+		default:
+			return fmt.Errorf("unknown skill action %q", act.Action)
+		}
+	case "mcp":
+		switch act.Action {
+		case "install_mcp_server":
+			return t.applyInstallMCP(ctx, req, act)
+		case "remove_mcp_server":
+			return t.applyRemoveMCP(req, act)
+		default:
+			return fmt.Errorf("unknown mcp action %q", act.Action)
+		}
+	default:
+		return fmt.Errorf("unknown install action kind %q", act.Kind)
+	}
+}
+
+// applySkillRoot appends the path to the active config's [skills].paths and
+// re-builds the Store to confirm the listed skills are discoverable.
+func (t *installSourceTool) applySkillRoot(req request, act *action) error {
+	cfg, err := t.loadConfig()
+	if err != nil {
+		return err
+	}
+	if err := cfg.AddSkillPath(act.Source); err != nil {
+		return err
+	}
+	if err := writeInstallConfigFile(act.ConfigPath, config.RenderSkillsTOML(cfg)); err != nil {
+		return err
+	}
+	store := skill.New(skill.Options{HomeDir: t.home, ProjectRoot: t.root, CustomPaths: append(cfg.SkillCustomPaths(), act.Source)})
+	for _, name := range act.Skills {
+		sk, ok := store.Read(name)
+		if !ok {
+			return newErr(ErrSourceUnreadable, "skill %q was registered but is not discoverable", name)
+		}
+		act.Discoverable = true
+		if act.CanonicalPath == "" && sk.Path != "" {
+			act.CanonicalPath = sk.Path
+		}
+		if strings.TrimSpace(sk.Description) == "" {
+			act.Warnings = append(act.Warnings, fmt.Sprintf("skill %q has no description frontmatter; it is installed but the skills index will use a placeholder", name))
+		}
+	}
+	for _, listed := range store.List() {
+		for _, name := range act.Skills {
+			if listed.Name == name {
+				act.Indexed = true
+				break
+			}
+		}
+	}
+	act.Target = act.Source
+	return nil
+}
+
+// applyCopySkill copies a single skill into the project/global skills dir.
+// We refuse to overwrite any existing canonical directory or legacy flat file.
+// copyDir uses O_EXCL so any race that slips through the Lstat check still
+// loses atomically.
+func (t *installSourceTool) applyCopySkill(req request, act *action) error {
+	canonical, err := t.skillCanonicalPath(act.skill.Name, req.Scope)
+	if err != nil {
+		return err
+	}
+	targetDir := filepath.Dir(canonical)
+	conflicts, err := t.skillConflictTargets(act.skill.Name, req.Scope)
+	if err != nil {
+		return err
+	}
+	for _, conflict := range conflicts {
+		if _, err := os.Lstat(conflict); err == nil {
+			return newErr(ErrAlreadyExists, "skill %q already exists at %s", act.skill.Name, conflict)
+		}
+	}
+	if act.skill.IsDir {
+		if err := copyDir(act.skill.SourcePath, targetDir); err != nil {
+			return err
+		}
+	} else {
+		if err := os.MkdirAll(targetDir, 0o755); err != nil {
+			return err
+		}
+		if err := writeNewFile(canonical, []byte(act.skill.Content)); err != nil {
+			return err
+		}
+	}
+	act.Target = canonical
+	act.CanonicalPath = canonical
+	return t.verifySkill(req.Scope, act.skill.Name, act)
+}
+
+// applyLinkSkill creates a symlink in the skills dir pointing at the source.
+// Absolute sources outside the project or home root are blocked even when the
+// plan was approved: a link-mode skill should not become a backdoor to arbitrary
+// host files.
+func (t *installSourceTool) applyLinkSkill(req request, act *action) error {
+	canonical, err := t.skillCanonicalPath(act.skill.Name, req.Scope)
+	if err != nil {
+		return err
+	}
+	target := canonical
+	if act.skill.IsDir {
+		target = filepath.Dir(canonical)
+	}
+	conflicts, err := t.skillConflictTargets(act.skill.Name, req.Scope)
+	if err != nil {
+		return err
+	}
+	for _, conflict := range conflicts {
+		if _, err := os.Lstat(conflict); err == nil {
+			return newErr(ErrAlreadyExists, "skill %q already exists at %s", act.skill.Name, conflict)
+		}
+	}
+	if !isLinkTargetSafe(act.skill.SourcePath, t.home, t.root) {
+		act.RiskLevel = RiskHigh
+		act.RiskReasons = append(act.RiskReasons, "link target is an absolute path outside the project or home root")
+		return newErr(ErrUnsafeLinkTarget, "skill %q source %s is outside %s and %s", act.skill.Name, act.skill.SourcePath, t.root, t.home)
+	}
+	if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+		return err
+	}
+	if err := os.Symlink(act.skill.SourcePath, target); err != nil {
+		return err
+	}
+	act.Target = target
+	act.CanonicalPath = canonical
+	return t.verifySkill(req.Scope, act.skill.Name, act)
+}
+
+// isLinkTargetSafe reports whether a symlink source is allowed. The link
+// target is safe when:
+//   - it is a relative path (we never follow the parent of a relative link),
+//   - or its absolute form is contained within the user's home or the
+//     project root.
+//
+// Absolute paths outside both scopes are rejected with ErrUnsafeLinkTarget
+// so a SKILL.md that points at /etc/passwd does not silently succeed.
+func isLinkTargetSafe(source, home, projectRoot string) bool {
+	if source == "" {
+		return false
+	}
+	if !filepath.IsAbs(source) {
+		return true
+	}
+	clean := filepath.Clean(source)
+	for _, root := range []string{home, projectRoot} {
+		if root == "" {
+			continue
+		}
+		base := filepath.Clean(root)
+		if clean == base {
+			return true
+		}
+		if strings.HasPrefix(clean, base+string(filepath.Separator)) {
+			return true
+		}
+	}
+	return false
+}
+
+// applyInstallMCP connects an MCP server and persists its config. The order
+// is deliberate: connect first (so the user can use the tools immediately),
+// then SaveTo (so a persistence failure is detectable). If SaveTo fails, we
+// roll back the connection and any tools the caller already registered, so
+// the live session is not out of sync with the on-disk config.
+func (t *installSourceTool) applyInstallMCP(ctx context.Context, req request, act *action) error {
+	if act.entry.Name == "" {
+		return newErr(ErrInvalidManifest, "MCP action has no server entry")
+	}
+	cfg, err := t.loadConfig()
+	if err != nil {
+		return err
+	}
+	var previous config.PluginEntry
+	hadPrevious := false
+	for _, existing := range cfg.Plugins {
+		if existing.Name == act.entry.Name {
+			previous = existing
+			hadPrevious = true
+			break
+		}
+	}
+	if !req.Replace {
+		if hadPrevious {
+			return newErr(ErrAlreadyExists, "MCP server %q already exists in %s; retry with replace=true to update it", act.entry.Name, act.ConfigPath)
+		}
+	}
+
+	var connected bool
+	oldDisconnected := false
+	if req.Replace && hadPrevious && t.onDisconnect != nil {
+		oldDisconnected = t.onDisconnect(act.entry.Name)
+	}
+	if t.connectMCP != nil {
+		res, err := t.connectMCP(act.entry)
+		if err != nil {
+			if oldDisconnected {
+				if rbErr := t.restoreMCP(previous); rbErr != nil {
+					return fmt.Errorf("%w; reconnect previous server failed: %v", err, rbErr)
+				}
+			}
+			return err
+		}
+		act.ToolCount = res.ToolCount
+		connected = res.Disconnect != nil || res.ToolCount >= 0
+		// Stash the disconnect on the action so a later SaveTo failure can
+		// undo the connect.
+		act.disconnect = res.Disconnect
+	}
+	if err := cfg.UpsertPlugin(act.entry); err != nil {
+		if rbErr := t.rollbackMCPReplace(act, previous, oldDisconnected, connected); rbErr != nil {
+			return fmt.Errorf("%w; rollback failed: %v", err, rbErr)
+		}
+		return err
+	}
+	if err := writeInstallConfigFile(act.ConfigPath, config.RenderMCPTOML(cfg.Plugins)); err != nil {
+		if rbErr := t.rollbackMCPReplace(act, previous, oldDisconnected, connected); rbErr != nil {
+			return fmt.Errorf("%w; rollback failed: %v", err, rbErr)
+		}
+		return err
+	}
+	return nil
+}
+
+func (t *installSourceTool) rollbackMCPReplace(act *action, previous config.PluginEntry, oldDisconnected, connected bool) error {
+	if connected && act.disconnect != nil {
+		act.disconnect()
+		act.disconnect = nil
+	}
+	if oldDisconnected {
+		return t.restoreMCP(previous)
+	}
+	return nil
+}
+
+func (t *installSourceTool) restoreMCP(previous config.PluginEntry) error {
+	if t.connectMCP == nil || previous.Name == "" {
+		return nil
+	}
+	_, err := t.connectMCP(previous)
+	return err
+}
+
+// applyRemoveSkill deletes a previously installed skill file or directory.
+// We only touch the project/global skills dir directly; the .mcp.json /
+// config file is not modified.
+func (t *installSourceTool) applyRemoveSkill(_ request, act *action) error {
+	target := act.Target
+	if target == "" {
+		return newErr(ErrInvalidManifest, "remove_skill action is missing target")
+	}
+	if _, err := os.Lstat(target); err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			act.Target = ""
+			return nil
+		}
+		return err
+	}
+	if err := os.RemoveAll(target); err != nil {
+		return err
+	}
+	act.Target = ""
+	return nil
+}
+
+func (t *installSourceTool) applyRemoveSkillRoot(_ request, act *action) error {
+	target := act.Target
+	if target == "" {
+		return newErr(ErrInvalidManifest, "remove_skill_root action is missing target")
+	}
+	cfg, err := t.loadConfig()
+	if err != nil {
+		return err
+	}
+	removed, err := cfg.RemoveSkillPath(target)
+	if err != nil {
+		return err
+	}
+	if !removed {
+		return nil
+	}
+	if err := writeInstallConfigFile(act.ConfigPath, config.RenderSkillsTOML(cfg)); err != nil {
+		return err
+	}
+	return nil
+}
+
+// applyRemoveMCP removes an MCP server entry from the active config and
+// asks the host to disconnect it (if a connector is wired).
+func (t *installSourceTool) applyRemoveMCP(_ request, act *action) error {
+	cfg, err := t.loadConfig()
+	if err != nil {
+		return err
+	}
+	if !cfg.RemovePlugin(act.Name) {
+		// Nothing to remove is not a failure: idempotent.
+		return nil
+	}
+	if err := writeInstallConfigFile(act.ConfigPath, config.RenderMCPTOML(cfg.Plugins)); err != nil {
+		return err
+	}
+	if t.onDisconnect != nil {
+		t.onDisconnect(act.Name)
+	}
+	return nil
+}
+
+func writeInstallConfigFile(path, body string) error {
+	if strings.TrimSpace(path) == "" {
+		return newErr(ErrInvalidManifest, "config path is empty")
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	return os.WriteFile(path, []byte(body), 0o600)
+}
diff --git a/internal/installsource/doc.go b/internal/installsource/doc.go
new file mode 100644
index 000000000..44fb6d1d4
--- /dev/null
+++ b/internal/installsource/doc.go
@@ -0,0 +1,18 @@
+// Package installsource implements the `install_source` tool: a two-phase
+// installer for Reasonix skills and MCP servers. A single call resolves a
+// source (URL, local file/folder, .mcp.json, package name, or local executable)
+// into a deterministic plan, then — only when the caller sets apply=true and
+// any registered ApprovalFunc consents — performs the writes and MCP connects.
+//
+// The two-phase design exists so the model (or a UI) can inspect a plan before
+// it touches disk or spawns subprocesses. `install_source` deliberately does
+// not run a README's `curl | sh` chain: it locates a concrete manifest
+// (SKILL.md / <name>.md / <name>/SKILL.md / nested skill roots / .mcp.json /
+// mcpServers entry) and describes what it would do, and only then does it act on
+// apply=true. Single skills are written to the canonical <name>/SKILL.md layout;
+// flat <name>.md is treated as compatibility input.
+//
+// Concurrency: each Execute call is independent; the tool does not lock the
+// filesystem. Callers that want to serialize installs (e.g. two parallel calls
+// for the same skill name) should do so in the host.
+package installsource
diff --git a/internal/installsource/errors.go b/internal/installsource/errors.go
new file mode 100644
index 000000000..b3b70a9cf
--- /dev/null
+++ b/internal/installsource/errors.go
@@ -0,0 +1,72 @@
+package installsource
+
+import (
+	"errors"
+	"fmt"
+)
+
+// RiskLevel classifies how dangerous an action is. The install-capability skill
+// prompt tells the model to call apply=true only when every action is low or
+// medium, or to ask the user first when any action is high.
+type RiskLevel string
+
+const (
+	// RiskLow is read-mostly safe: copy/link of a single skill file, or
+	// connecting an MCP endpoint whose URL the user already trusts.
+	RiskLow RiskLevel = "low"
+	// RiskMedium is a write that mutates the active config (new MCP server,
+	// new skill registered into a project root the user already shares).
+	RiskMedium RiskLevel = "medium"
+	// RiskHigh is a write the user almost certainly wants to see first: a
+	// symlink target outside any expected scope, a remote URL with auth
+	// headers, a package name that triggers an out-of-process fetch, or a
+	// replace of an existing MCP server.
+	RiskHigh RiskLevel = "high"
+)
+
+// Sentinel errors. Callers use errors.Is to map a failure to a remediation
+// hint without scraping error messages.
+var (
+	// ErrAuthRequired: the upstream demanded credentials that the request
+	// did not carry. Surface a hint to set the relevant env var or header.
+	ErrAuthRequired = errors.New("install_source: authentication required")
+	// ErrBinaryMissing: a stdio MCP server references a command that is not
+	// on PATH or not present at the given path.
+	ErrBinaryMissing = errors.New("install_source: command or runtime not found")
+	// ErrAlreadyExists: a target file / config entry already exists and the
+	// call did not opt into replace=true.
+	ErrAlreadyExists = errors.New("install_source: target already exists")
+	// ErrUnsafeLinkTarget: a link-mode skill install would create a symlink
+	// that escapes the expected skill roots — typically an attempt to
+	// read arbitrary host files.
+	ErrUnsafeLinkTarget = errors.New("install_source: link target escapes skill roots")
+	// ErrSourceUnreadable: a URL did not respond, returned non-2xx, or a
+	// local path was not readable.
+	ErrSourceUnreadable = errors.New("install_source: source is not readable")
+	// ErrManifestMissing: a path was reachable but contained no installable
+	// artifact (no SKILL.md, no .mcp.json, no executable, etc.).
+	ErrManifestMissing = errors.New("install_source: no installable manifest")
+	// ErrInvalidManifest: a manifest existed but did not validate (missing
+	// required fields, unknown transport, etc.).
+	ErrInvalidManifest = errors.New("install_source: manifest did not validate")
+	// ErrUnsupportedKind: kind was set explicitly to something the resolver
+	// cannot satisfy (e.g. kind=skill for a remote MCP endpoint).
+	ErrUnsupportedKind = errors.New("install_source: kind does not match source")
+	// ErrApprovalDenied: the host's ApprovalFunc returned a non-nil error,
+	// or the call set apply=true while the host requires explicit consent.
+	ErrApprovalDenied = errors.New("install_source: host denied the install")
+)
+
+// errKind wraps a sentinel with a human-readable detail so logs and the
+// `next` field stay useful.
+type errKind struct {
+	sentinel error
+	detail   string
+}
+
+func (e *errKind) Error() string { return fmt.Sprintf("%s: %s", e.sentinel, e.detail) }
+func (e *errKind) Unwrap() error { return e.sentinel }
+
+func newErr(sentinel error, format string, args ...any) error {
+	return &errKind{sentinel: sentinel, detail: fmt.Sprintf(format, args...)}
+}
diff --git a/internal/installsource/http.go b/internal/installsource/http.go
new file mode 100644
index 000000000..f836beae9
--- /dev/null
+++ b/internal/installsource/http.go
@@ -0,0 +1,55 @@
+package installsource
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"time"
+)
+
+// defaultFetchTimeout caps the lifetime of a single HTTP fetch. Without it a
+// slow CDN can hold the agent tool call open until the user gives up. The
+// value is generous (30s) so large SKILL.md bodies still load, but bounded so
+// a hung server is not an open-ended wait.
+const defaultFetchTimeout = 30 * time.Second
+
+// defaultFetchLimit is the maximum body size we will accept from a remote
+// manifest. SKILL.md / .mcp.json files are normally a few KB; 2 MiB is a
+// safety cap that prevents an untrusted mirror from streaming gigabytes into
+// our parser.
+const defaultFetchLimit = 2 << 20
+
+// fetchText performs a bounded GET on sourceURL using the tool's HTTP client.
+// It applies defaultFetchTimeout unless the caller's context already has a
+// tighter deadline, and never reads more than defaultFetchLimit bytes.
+func (t *installSourceTool) fetchText(ctx context.Context, sourceURL string) (string, error) {
+	if _, hasDeadline := ctx.Deadline(); !hasDeadline {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, defaultFetchTimeout)
+		defer cancel()
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, sourceURL, nil)
+	if err != nil {
+		return "", newErr(ErrSourceUnreadable, "%s: %v", sourceURL, err)
+	}
+	if req.Header.Get("User-Agent") == "" {
+		req.Header.Set("User-Agent", "reasonix-install/1.0")
+	}
+	resp, err := t.httpClient.Do(req)
+	if err != nil {
+		return "", newErr(ErrSourceUnreadable, "%s: %v", sourceURL, err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		return "", newErr(ErrAuthRequired, "%s: HTTP %d", sourceURL, resp.StatusCode)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return "", newErr(ErrSourceUnreadable, "%s: HTTP %d", sourceURL, resp.StatusCode)
+	}
+	limited := io.LimitReader(resp.Body, defaultFetchLimit)
+	body, err := io.ReadAll(limited)
+	if err != nil {
+		return "", newErr(ErrSourceUnreadable, "%s: read body: %v", sourceURL, err)
+	}
+	return string(body), nil
+}
diff --git a/internal/installsource/install_source.go b/internal/installsource/install_source.go
new file mode 100644
index 000000000..42c06d640
--- /dev/null
+++ b/internal/installsource/install_source.go
@@ -0,0 +1,648 @@
+// Package installsource: install_source.go is the tool entrypoint. It
+// defines the public Options/Execute surface, the JSON Schema, and the
+// end-to-end pipeline that turns a request into a plan and (optionally)
+// into a series of apply calls.
+package installsource
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/BurntSushi/toml"
+
+	"reasonix/internal/config"
+	"reasonix/internal/skill"
+	"reasonix/internal/tool"
+)
+
+// MCPConnectResult is what the ConnectMCP callback returns. Disconnect is
+// optional; when non-nil, the apply step will call it to undo a connect
+// whose persistence (SaveTo) failed — closing the "ghost install" window.
+type MCPConnectResult struct {
+	ToolCount  int
+	Disconnect func() // optional; nil means rollback is not possible
+}
+
+// MCPConnector is the host-provided hook that turns a PluginEntry into a
+// live MCP connection. The returned Disconnect, if any, is used by the
+// install_source tool to roll back a failed persistence step.
+type MCPConnector func(config.PluginEntry) (MCPConnectResult, error)
+
+// ApprovalFunc is invoked between plan and apply when apply=true. Return
+// nil to allow the install, or a non-nil error to refuse it. The action
+// list reflects the exact set the apply step is about to perform; a host
+// (e.g. the desktop TUI) can show it to the user and decide synchronously.
+type ApprovalFunc func(actions []action) error
+
+// OnDisconnectFunc tells the host to remove a server from the live session and
+// drop the corresponding mcp__<name>__ tools from its Registry. It returns true
+// when a live server was actually removed, letting replace/rollback restore the
+// old connection only when there was one.
+type OnDisconnectFunc func(serverName string) bool
+
+// Options configure the install_source tool. ProjectRoot "" and HomeDir
+// "" fall back to os.Getwd / os.UserHomeDir at construction time.
+type Options struct {
+	ProjectRoot  string
+	HomeDir      string
+	HTTPClient   *http.Client
+	ConnectMCP   MCPConnector
+	OnDisconnect OnDisconnectFunc
+	Approval     ApprovalFunc
+}
+
+type installSourceTool struct {
+	root         string
+	home         string
+	httpClient   *http.Client
+	connectMCP   MCPConnector
+	onDisconnect OnDisconnectFunc
+	approval     ApprovalFunc
+}
+
+// NewTool returns a tool.Tool that callers register with the agent's
+// Registry. The returned tool is safe to call from any goroutine; the
+// underlying config/config.SaveTo paths do their own per-file locking.
+func NewTool(opts Options) tool.Tool {
+	root := opts.ProjectRoot
+	if root == "" {
+		if wd, err := currentDir(); err == nil {
+			root = wd
+		}
+	}
+	if abs, err := filepath.Abs(root); err == nil {
+		root = abs
+	}
+	home := opts.HomeDir
+	if home == "" {
+		if h, err := userHomeDir(); err == nil {
+			home = h
+		}
+	}
+	client := opts.HTTPClient
+	if client == nil {
+		client = &http.Client{}
+	}
+	return &installSourceTool{
+		root:         root,
+		home:         home,
+		httpClient:   client,
+		connectMCP:   opts.ConnectMCP,
+		onDisconnect: opts.OnDisconnect,
+		approval:     opts.Approval,
+	}
+}
+
+func (*installSourceTool) Name() string   { return "install_source" }
+func (*installSourceTool) ReadOnly() bool { return false }
+
+func (*installSourceTool) Description() string {
+	return "Plan, install, or uninstall a Reasonix skill or MCP server from a URL, local file/folder, .mcp.json, executable, or package name. Two-phase: with apply=false (default) returns a deterministic plan with per-action risk level; with apply=true copies/registers skills or connects and persists MCP servers after validation. op='uninstall' removes a previously installed skill (by name) or MCP server (by name) from the active config and the live session."
+}
+
+func (*installSourceTool) Schema() json.RawMessage {
+	return json.RawMessage(`{
+"type":"object",
+"properties":{
+  "op":{"type":"string","enum":["install","uninstall"],"description":"Whether to install (default) or uninstall."},
+  "source":{"type":"string","description":"URL, local file/folder path, .mcp.json path, or package name to install from. Ignored when op=uninstall (use name instead)."},
+  "kind":{"type":"string","enum":["auto","skill","mcp"],"description":"Capability kind. Defaults to auto."},
+  "apply":{"type":"boolean","description":"false (default) only returns an install plan; true performs the planned writes/connects. Ignored for op=uninstall."},
+  "scope":{"type":"string","enum":["project","global"],"description":"Where to persist config or copy skills. Defaults to project when a workspace exists, otherwise global."},
+  "mode":{"type":"string","enum":["auto","copy","link","register"],"description":"Skill install mode. auto registers multi-skill roots and copies single skills into the canonical <skill-name>/SKILL.md layout; copy copies skill files/folders; link creates symlinks; register adds a skill root to [skills].paths."},
+  "name":{"type":"string","description":"Optional override for the installed MCP server or single skill name. Required for op=uninstall when removing by name."},
+  "transport":{"type":"string","enum":["auto","stdio","http","sse"],"description":"MCP transport override. URL sources default to http unless --sse-like; package sources default to stdio."},
+  "command":{"type":"string","description":"Optional stdio MCP command override for package/local executable installs."},
+  "args":{"type":"array","items":{"type":"string"},"description":"Optional stdio MCP args override."},
+  "env":{"type":"object","additionalProperties":{"type":"string"},"description":"Environment variables for stdio MCP servers."},
+  "headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers for remote MCP servers. Prefer ${VAR} placeholders for secrets."},
+  "tier":{"type":"string","enum":["lazy","background","eager"],"description":"Persisted MCP startup tier. Defaults to lazy."},
+  "replace":{"type":"boolean","description":"Allow replacing an existing MCP config entry with the same name. Skills still refuse to overwrite existing files."},
+  "strict":{"type":"boolean","description":"Skill install strictness. true (default) requires name+description frontmatter; false copies the file as-is (use only for files you trust)."},
+  "planId":{"type":"string","description":"Optional. Echoed from a previous planned response to confirm the host is approving the same plan."}
+},
+"required":[]
+}`)
+}
+
+// Execute parses args, plans, and (if apply=true and Approval allows)
+// performs the writes. JSON output is always returned on success even when
+// the plan is empty, so the model can read structured `next` hints.
+func (t *installSourceTool) Execute(ctx context.Context, raw json.RawMessage) (string, error) {
+	var req request
+	if err := json.Unmarshal(raw, &req); err != nil {
+		return "", fmt.Errorf("install_source: invalid args: %w", err)
+	}
+	req.Source = strings.TrimSpace(req.Source)
+	if req.Op == "" {
+		req.Op = "install"
+	}
+	if req.Op != "install" && req.Op != "uninstall" {
+		return "", fmt.Errorf("install_source: op %q is not supported (want install|uninstall)", req.Op)
+	}
+	if req.Op == "install" && req.Source == "" {
+		return "", errors.New("install_source requires a non-empty source")
+	}
+	if req.Op == "uninstall" && strings.TrimSpace(req.Name) == "" {
+		return "", errors.New("install_source: op=uninstall requires a non-empty name")
+	}
+	req.Kind = normalizeKind(req.Kind)
+	req.Scope = t.normalizeScope(req.Scope)
+	req.Mode = normalizeMode(req.Mode)
+	req.Transport = normalizeTransport(req.Transport)
+	if norm, ok := normalizeTier(req.Tier); ok {
+		req.Tier = norm
+	}
+
+	if req.Op == "uninstall" {
+		return t.executeUninstall(req), nil
+	}
+
+	actions, warnings, err := t.plan(ctx, req)
+	if err != nil {
+		return "", err
+	}
+	planID := computePlanID(req, actions)
+	if len(actions) == 0 {
+		out := response{
+			OK:       false,
+			Status:   "blocked",
+			Op:       req.Op,
+			Applied:  false,
+			Source:   req.Source,
+			Kind:     "",
+			Scope:    req.Scope,
+			Mode:     req.Mode,
+			PlanID:   planID,
+			Warnings: warnings,
+			Next:     "No installable Reasonix skill or MCP server was detected. Ask the user for a direct SKILL.md, skill root, .mcp.json, MCP endpoint, or package name.",
+		}
+		return marshalJSON(out), nil
+	}
+
+	if !req.Apply {
+		for i := range actions {
+			actions[i].Status = "planned"
+		}
+		out := response{
+			OK:       true,
+			Status:   "planned",
+			Op:       req.Op,
+			Applied:  false,
+			Source:   req.Source,
+			Kind:     summarizeKind(actions),
+			Kinds:    kindCounts(actions),
+			Scope:    req.Scope,
+			Mode:     req.Mode,
+			PlanID:   planID,
+			Actions:  publicActions(actions),
+			Warnings: warnings,
+			Next:     "Review the plan (especially each action's riskLevel). Call install_source again with apply=true and the same planId to install.",
+		}
+		return marshalJSON(out), nil
+	}
+
+	if req.PlanID != "" && req.PlanID != planID {
+		return "", newErr(ErrApprovalDenied, "planId mismatch (got %s, expected %s); re-plan and re-approve", req.PlanID, planID)
+	}
+	if t.approval != nil {
+		if err := t.approval(publicActions(actions)); err != nil {
+			return marshalJSON(response{
+				OK:       false,
+				Status:   "denied",
+				Op:       req.Op,
+				Applied:  false,
+				Source:   req.Source,
+				Kind:     summarizeKind(actions),
+				Kinds:    kindCounts(actions),
+				Scope:    req.Scope,
+				Mode:     req.Mode,
+				PlanID:   planID,
+				Actions:  publicActions(actions),
+				Warnings: append(warnings, "host approval was denied: "+err.Error()),
+				Next:     "Ask the user to confirm, or run with a less risky plan (e.g. lower scope, fewer actions).",
+			}), nil
+		}
+	}
+
+	return t.executeApply(ctx, req, actions, warnings, planID), nil
+}
+
+// executeApply runs the apply phase. The first failed action short-circuits
+// the rest only when a single failure implies the plan is unusable; for
+// MCP installs in particular, partial completion is reported honestly.
+func (t *installSourceTool) executeApply(ctx context.Context, req request, actions []action, warnings []string, planID string) string {
+	ok := true
+	anySucceeded := false
+	for i := range actions {
+		if err := t.apply(ctx, req, &actions[i]); err != nil {
+			ok = false
+			actions[i].Status = "failed"
+			actions[i].Error = err.Error()
+			if actions[i].Next == "" {
+				actions[i].Next = nextForError(err)
+			}
+			continue
+		}
+		actions[i].Status = "done"
+		anySucceeded = true
+		warnings = append(warnings, actions[i].Warnings...)
+	}
+	status := "done"
+	next := "Installed and verified."
+	if !ok {
+		if anySucceeded {
+			status = "partial"
+			next = "Some actions succeeded; the failed ones are listed in actions[].status=failed. Re-plan those and retry."
+		} else {
+			status = "failed"
+			next = "No action succeeded. Fix the first failed action[] entry and retry install_source with apply=true."
+		}
+	}
+	return marshalJSON(response{
+		OK:       ok,
+		Status:   status,
+		Op:       req.Op,
+		Applied:  true,
+		Source:   req.Source,
+		Kind:     summarizeKind(actions),
+		Kinds:    kindCounts(actions),
+		Scope:    req.Scope,
+		Mode:     req.Mode,
+		PlanID:   planID,
+		Actions:  publicActions(actions),
+		Warnings: warnings,
+		Next:     next,
+	})
+}
+
+// executeUninstall handles op=uninstall. It locates the named entry in the
+// active config (skills via the on-disk layout, MCP via cfg.Plugins) and
+// asks the host to disconnect. We do not consult the approval hook for
+// uninstall: the user already named the entry, and removal is the inverse
+// of the install they authorized.
+func (t *installSourceTool) executeUninstall(req request) string {
+	scope := req.Scope
+	actions := []action{}
+	cfg, err := t.loadConfig()
+	if err != nil {
+		return marshalJSON(response{
+			OK:      false,
+			Status:  "blocked",
+			Op:      req.Op,
+			Applied: false,
+			Source:  req.Source,
+			Name:    req.Name,
+			Scope:   scope,
+			Next:    "The active install config could not be loaded: " + err.Error(),
+		})
+	}
+	skillCfgPath := t.skillConfigPath(scope)
+	mcpCfgPath := t.mcpConfigPath(scope)
+
+	// Skills: try the flat file, then the directory layout, in the chosen
+	// scope. We don't require a kind — "name" disambiguates.
+	if path, ok := t.resolveSkillPath(req.Name, scope); ok {
+		actions = append(actions, action{
+			Kind:       "skill",
+			Action:     "remove_skill",
+			Name:       req.Name,
+			Target:     path,
+			Scope:      scope,
+			ConfigPath: skillCfgPath,
+			RiskLevel:  RiskLow,
+		})
+	} else if rootAction, ok := t.resolveRegisteredSkillRoot(req.Name, scope, skillCfgPath, cfg); ok {
+		actions = append(actions, rootAction)
+	}
+
+	// MCP: scan the chosen config for the named plugin.
+	for _, p := range cfg.Plugins {
+		if p.Name == req.Name {
+			actions = append(actions, action{
+				Kind:       "mcp",
+				Action:     "remove_mcp_server",
+				Name:       p.Name,
+				Target:     p.URL,
+				Scope:      scope,
+				Transport:  pluginTransport(p),
+				ConfigPath: mcpCfgPath,
+				RiskLevel:  RiskMedium,
+				RiskReasons: []string{
+					"disconnects a running server and drops its tools from the active session",
+				},
+			})
+			break
+		}
+	}
+
+	if len(actions) == 0 {
+		return marshalJSON(response{
+			OK:      false,
+			Status:  "blocked",
+			Op:      req.Op,
+			Applied: false,
+			Source:  req.Source,
+			Name:    req.Name,
+			Scope:   scope,
+			Next:    "No installed skill or MCP server matched that name in the chosen scope.",
+		})
+	}
+
+	// Uninstall is destructive but symmetric with a previously approved
+	// install, so we apply directly. Each action is independent.
+	ok := true
+	anySucceeded := false
+	for i := range actions {
+		if err := t.apply(context.Background(), req, &actions[i]); err != nil {
+			ok = false
+			actions[i].Status = "failed"
+			actions[i].Error = err.Error()
+			actions[i].Next = "Inspect the error, then retry op=uninstall."
+			continue
+		}
+		actions[i].Status = "done"
+		anySucceeded = true
+	}
+	status := "done"
+	if !ok {
+		status = "partial"
+		if !anySucceeded {
+			status = "failed"
+		}
+	}
+	return marshalJSON(response{
+		OK:      ok,
+		Status:  status,
+		Op:      req.Op,
+		Applied: true,
+		Source:  req.Source,
+		Name:    req.Name,
+		Kind:    summarizeKind(actions),
+		Kinds:   kindCounts(actions),
+		Scope:   scope,
+		Actions: publicActions(actions),
+		Next:    "Removed.",
+	})
+}
+
+// resolveSkillPath finds the on-disk location of a previously installed
+// skill of the given name in the chosen scope. The bool reports whether
+// the path is a real install (Lstat succeeded). Both flat (<name>.md) and
+// directory (<name>/) layouts are checked.
+func (t *installSourceTool) resolveSkillPath(name, scope string) (string, bool) {
+	if !config.IsValidSkillName(name) {
+		return "", false
+	}
+	var root string
+	if scope == "global" {
+		if t.home == "" {
+			return "", false
+		}
+		root = filepath.Join(t.home, ".reasonix", skill.SkillsDirname)
+	} else {
+		root = filepath.Join(t.root, ".reasonix", skill.SkillsDirname)
+	}
+	flat := filepath.Join(root, name+".md")
+	if _, err := lstat(flat); err == nil {
+		return flat, true
+	}
+	dir := filepath.Join(root, name)
+	if _, err := lstat(filepath.Join(dir, skill.SkillFile)); err == nil {
+		return dir, true
+	}
+	return "", false
+}
+
+func (t *installSourceTool) resolveRegisteredSkillRoot(name, scope, cfgPath string, cfg *config.Config) (action, bool) {
+	if !config.IsValidSkillName(name) {
+		return action{}, false
+	}
+	for _, rawPath := range cfg.Skills.Paths {
+		path := t.resolvePath(config.ExpandVars(rawPath))
+		cands, err := scanSkillRoot(path, false)
+		if err != nil {
+			continue
+		}
+		var names []string
+		found := false
+		for _, cand := range cands {
+			names = append(names, cand.Name)
+			if cand.Name == name {
+				found = true
+			}
+		}
+		if !found {
+			continue
+		}
+		sort.Strings(names)
+		return action{
+			Kind:       "skill",
+			Action:     "remove_skill_root",
+			Name:       name,
+			Target:     rawPath,
+			Scope:      scope,
+			ConfigPath: cfgPath,
+			Skills:     names,
+			SkillCount: len(names),
+			RiskLevel:  RiskMedium,
+			RiskReasons: []string{
+				"removes a registered skill root from [skills].paths and may hide every skill in that folder",
+			},
+		}, true
+	}
+	return action{}, false
+}
+
+func (t *installSourceTool) configPath(scope string) string {
+	if scope == "global" {
+		if t.home != "" {
+			return filepath.Join(t.home, ".reasonix", "config.toml")
+		}
+	}
+	return filepath.Join(t.root, "reasonix.toml")
+}
+
+func (t *installSourceTool) skillConfigPath(scope string) string {
+	if scope == "global" {
+		if t.home != "" {
+			return filepath.Join(t.home, ".reasonix", "skills.toml")
+		}
+	}
+	return t.configPath(scope)
+}
+
+func (t *installSourceTool) mcpConfigPath(scope string) string {
+	if scope == "global" {
+		if t.home != "" {
+			return filepath.Join(t.home, ".reasonix", "mcp.toml")
+		}
+	}
+	return t.configPath(scope)
+}
+
+func (t *installSourceTool) loadConfig() (*config.Config, error) {
+	cfg := config.LoadForEdit(t.configPath("global"))
+	if path := t.skillConfigPath("global"); path != "" {
+		var top struct {
+			Skills config.SkillsConfig `toml:"skills"`
+		}
+		if _, err := os.Stat(path); err == nil {
+			if _, err := toml.DecodeFile(path, &top); err != nil {
+				return nil, err
+			}
+			cfg.Skills = top.Skills
+		}
+	}
+	if path := t.mcpConfigPath("global"); path != "" {
+		var top struct {
+			Plugins []config.PluginEntry `toml:"plugins"`
+		}
+		if _, err := os.Stat(path); err == nil {
+			if _, err := toml.DecodeFile(path, &top); err != nil {
+				return nil, err
+			}
+			cfg.Plugins = top.Plugins
+			for i := range cfg.Plugins {
+				cfg.Plugins[i], _ = config.NormalizePluginCommandLine(cfg.Plugins[i])
+			}
+		}
+	}
+	return cfg, nil
+}
+
+func (t *installSourceTool) normalizeScope(scope string) string {
+	switch strings.ToLower(strings.TrimSpace(scope)) {
+	case "global", "project":
+		return "global"
+	default:
+		return "global"
+	}
+}
+
+func (t *installSourceTool) resolvePath(p string) string {
+	p = strings.TrimSpace(p)
+	if strings.HasPrefix(p, "~/") || strings.HasPrefix(p, `~\`) {
+		p = filepath.Join(t.home, p[2:])
+	} else if p == "~" {
+		p = t.home
+	}
+	if !filepath.IsAbs(p) {
+		p = filepath.Join(t.root, p)
+	}
+	if abs, err := filepath.Abs(p); err == nil {
+		p = abs
+	}
+	return filepath.Clean(p)
+}
+
+// computePlanID hashes the request plus the full public action set so a later
+// apply call with the same planId can be verified to be approving exactly the
+// same plan. It intentionally excludes Apply and PlanID; everything that changes
+// what will be written/connected must live either in req's planning fields or in
+// the action DTO.
+func computePlanID(req request, actions []action) string {
+	public := publicActions(actions)
+	sort.Slice(public, func(i, j int) bool {
+		return actionPlanKey(public[i]) < actionPlanKey(public[j])
+	})
+	payload := struct {
+		Op        string            `json:"op"`
+		Source    string            `json:"source"`
+		Kind      string            `json:"kind"`
+		Scope     string            `json:"scope"`
+		Mode      string            `json:"mode"`
+		Name      string            `json:"name"`
+		Transport string            `json:"transport"`
+		Command   string            `json:"command"`
+		Args      []string          `json:"args,omitempty"`
+		Env       map[string]string `json:"env,omitempty"`
+		Headers   map[string]string `json:"headers,omitempty"`
+		Tier      string            `json:"tier"`
+		Replace   bool              `json:"replace"`
+		Strict    bool              `json:"strict"`
+		Actions   []action          `json:"actions"`
+	}{
+		Op:        req.Op,
+		Source:    req.Source,
+		Kind:      req.Kind,
+		Scope:     req.Scope,
+		Mode:      req.Mode,
+		Name:      req.Name,
+		Transport: req.Transport,
+		Command:   req.Command,
+		Args:      req.Args,
+		Env:       req.Env,
+		Headers:   req.Headers,
+		Tier:      req.Tier,
+		Replace:   req.Replace,
+		Strict:    req.strict(),
+		Actions:   public,
+	}
+	body, _ := json.Marshal(payload)
+	h := sha256.New()
+	h.Write(body)
+	return "sha256:" + hex.EncodeToString(h.Sum(nil)[:16])
+}
+
+// kindCounts tallies the per-kind action count for the response. Skill
+// skills and MCP servers in the same plan get separate counts so the
+// caller can summarize accurately.
+func kindCounts(actions []action) kindTally {
+	var out kindTally
+	for _, a := range actions {
+		switch a.Kind {
+		case "skill":
+			out.Skill++
+		case "mcp":
+			out.MCP++
+		}
+	}
+	return out
+}
+
+// nextForError maps a sentinel error to a short remediation hint. Callers
+// use it as the default `next` value when a plan step fails.
+func nextForError(err error) string {
+	switch {
+	case errors.Is(err, ErrAuthRequired):
+		return "Authentication is required. Add the needed token as an environment variable or header placeholder, then retry."
+	case errors.Is(err, ErrBinaryMissing):
+		return "Install the missing local runtime or use an absolute command path, then retry."
+	case errors.Is(err, ErrAlreadyExists):
+		return "Choose another name, remove the existing entry, or retry MCP installs with replace=true."
+	case errors.Is(err, ErrUnsafeLinkTarget):
+		return "The link target escapes the project/home root. Pick a source path inside the workspace or home directory."
+	case errors.Is(err, ErrApprovalDenied):
+		return "Host denied the install. Re-run without apply=true to revise the plan, or ask the user to confirm."
+	case errors.Is(err, ErrManifestMissing):
+		return "No installable manifest was found at the source. Provide a direct SKILL.md, .mcp.json, executable, or package name."
+	case errors.Is(err, ErrInvalidManifest):
+		return "The manifest was found but did not validate. Check required fields (command/url/tier)."
+	case errors.Is(err, ErrSourceUnreadable):
+		return "The source could not be read. Check the URL/path and try again."
+	default:
+		return "Inspect the error, fix the source or environment, then retry."
+	}
+}
+
+// currentDir / userHomeDir / lstat are tiny wrappers that exist so tests
+// can stub them; the wrappers today just call the stdlib versions.
+var (
+	currentDir  = defaultCurrentDir
+	userHomeDir = defaultUserHomeDir
+	lstat       = defaultLstat
+)
+
+func defaultCurrentDir() (string, error)            { return os.Getwd() }
+func defaultUserHomeDir() (string, error)           { return os.UserHomeDir() }
+func defaultLstat(path string) (os.FileInfo, error) { return os.Lstat(path) }
diff --git a/internal/installsource/install_source_test.go b/internal/installsource/install_source_test.go
new file mode 100644
index 000000000..aa8829a62
--- /dev/null
+++ b/internal/installsource/install_source_test.go
@@ -0,0 +1,1331 @@
+package installsource
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"reasonix/internal/config"
+	"reasonix/internal/skill"
+	"reasonix/internal/tool"
+)
+
+// --- shared helpers ---------------------------------------------------------
+
+// execInstall marshals args, calls Execute, and unmarshals the response.
+// Failures in Execute bubble up as t.Fatal; the response is returned so the
+// caller can assert on the JSON shape.
+func execInstall(t *testing.T, tl tool.Tool, args map[string]any) response {
+	t.Helper()
+	raw, err := json.Marshal(args)
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := tl.Execute(context.Background(), raw)
+	if err != nil {
+		t.Fatalf("Execute error: %v\nout=%s", err, out)
+	}
+	var resp response
+	if err := json.Unmarshal([]byte(out), &resp); err != nil {
+		t.Fatalf("response JSON %q: %v", out, err)
+	}
+	return resp
+}
+
+func writeFile(t *testing.T, path, content string) {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func skillConfigPathForHome(home string) string {
+	return filepath.Join(home, ".reasonix", "skills.toml")
+}
+
+func mcpConfigPathForHome(home string) string {
+	return filepath.Join(home, ".reasonix", "mcp.toml")
+}
+
+func skillInstallPath(home string, elems ...string) string {
+	parts := append([]string{home, ".reasonix", "skills"}, elems...)
+	return filepath.Join(parts...)
+}
+
+func loadSkillsConfigForHome(home string) *config.Config {
+	return config.LoadForEdit(skillConfigPathForHome(home))
+}
+
+func loadMCPConfigForHome(home string) *config.Config {
+	return config.LoadForEdit(mcpConfigPathForHome(home))
+}
+
+func saveMCPConfigForHome(t *testing.T, home string, cfg *config.Config) {
+	t.Helper()
+	if err := writeInstallConfigFile(mcpConfigPathForHome(home), config.RenderMCPTOML(cfg.Plugins)); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func registeredRoots(actions []action) []string {
+	var roots []string
+	for _, a := range actions {
+		if a.Action == "register_skill_root" {
+			roots = append(roots, a.Source)
+		}
+	}
+	return roots
+}
+
+// stubConnector returns a ConnectMCP closure that records every entry and
+// returns the configured tool count + Disconnect. disconnectCalls counts
+// rollback invocations so tests can assert on ghost-install behavior.
+type stubConnector struct {
+	connected       []config.PluginEntry
+	toolCount       int
+	failOnName      string
+	disconnectCalls *atomic.Int32
+}
+
+func (s *stubConnector) connector() MCPConnector {
+	return func(e config.PluginEntry) (MCPConnectResult, error) {
+		if e.Name == s.failOnName {
+			return MCPConnectResult{}, errors.New("connect refused: " + e.Name)
+		}
+		s.connected = append(s.connected, e)
+		return MCPConnectResult{
+			ToolCount: s.toolCount,
+			Disconnect: func() {
+				if s.disconnectCalls != nil {
+					s.disconnectCalls.Add(1)
+				}
+			},
+		}, nil
+	}
+}
+
+// --- apply: skill paths -----------------------------------------------------
+
+func TestApplyLocalSkillRootRegistersPath(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	root := filepath.Join(t.TempDir(), "shared-skills")
+	if err := os.MkdirAll(root, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	writeFile(t, filepath.Join(root, "alpha.md"), "---\nname: alpha\ndescription: Alpha helper\n---\nDo alpha work.")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": root,
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+	})
+
+	if !resp.OK || resp.Status != "done" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if len(resp.Actions) != 1 || resp.Actions[0].Action != "register_skill_root" {
+		t.Fatalf("actions = %+v", resp.Actions)
+	}
+	if resp.PlanID == "" {
+		t.Error("PlanID should be populated on apply")
+	}
+	cfg := loadSkillsConfigForHome(home)
+	if len(cfg.Skills.Paths) != 1 || cfg.Skills.Paths[0] != root {
+		t.Fatalf("skills.paths = %v, want %q", cfg.Skills.Paths, root)
+	}
+	st := skill.New(skill.Options{HomeDir: home, ProjectRoot: project, CustomPaths: cfg.SkillCustomPaths(), DisableBuiltins: true})
+	if _, ok := st.Read("alpha"); !ok {
+		t.Fatal("alpha should be discoverable after registering the skill root")
+	}
+}
+
+func TestApplyLocalSkillFileCopiesToProject(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	src := filepath.Join(t.TempDir(), "beta.md")
+	writeFile(t, src, "---\nname: beta\ndescription: Beta helper\n---\nDo beta work.")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+	})
+
+	if !resp.OK || resp.Actions[0].Action != "copy_skill" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].RiskLevel != RiskLow {
+		t.Errorf("copy of a single file should be RiskLow, got %q", resp.Actions[0].RiskLevel)
+	}
+	target := skillInstallPath(home, "beta", "SKILL.md")
+	if raw, err := os.ReadFile(target); err != nil || !strings.Contains(string(raw), "Beta helper") {
+		t.Fatalf("copied skill = %q err=%v", raw, err)
+	}
+	if resp.Actions[0].CanonicalPath != target || !resp.Actions[0].Discoverable || !resp.Actions[0].Indexed {
+		t.Fatalf("skill verification fields = %+v, want canonical/discoverable/indexed", resp.Actions[0])
+	}
+}
+
+func TestApplyLocalSkillFileDoesNotShadowFlatCompatInstall(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	existing := skillInstallPath(home, "beta.md")
+	writeFile(t, existing, "---\nname: beta\ndescription: Existing beta\n---\nold")
+	src := filepath.Join(t.TempDir(), "beta.md")
+	writeFile(t, src, "---\nname: beta\ndescription: New beta\n---\nnew")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+	})
+
+	if resp.OK {
+		t.Fatalf("canonical install should not shadow existing flat skill, got %+v", resp)
+	}
+	if !strings.Contains(resp.Actions[0].Error, "already exists") {
+		t.Fatalf("error = %q, want duplicate guard", resp.Actions[0].Error)
+	}
+}
+
+func TestApplyLocalSKILLFileCopiesSiblingResources(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	srcDir := filepath.Join(t.TempDir(), "frontend-design")
+	writeFile(t, filepath.Join(srcDir, "SKILL.md"), "---\nname: frontend-design\ndescription: Frontend helper\n---\nSee references/style.md")
+	writeFile(t, filepath.Join(srcDir, "references", "style.md"), "# Style\n\nUse crisp layouts.")
+	writeFile(t, filepath.Join(srcDir, "scripts", "lint.sh"), "#!/bin/sh\nexit 0\n")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": filepath.Join(srcDir, "SKILL.md"),
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+	})
+
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].RiskLevel != RiskMedium {
+		t.Fatalf("directory package copy should be RiskMedium, got %q", resp.Actions[0].RiskLevel)
+	}
+	target := skillInstallPath(home, "frontend-design", "SKILL.md")
+	if resp.Actions[0].CanonicalPath != target {
+		t.Fatalf("canonicalPath = %q, want %q", resp.Actions[0].CanonicalPath, target)
+	}
+	if _, err := os.Stat(skillInstallPath(home, "frontend-design", "references", "style.md")); err != nil {
+		t.Fatalf("reference file should be copied with SKILL.md source: %v", err)
+	}
+	if _, err := os.Stat(skillInstallPath(home, "frontend-design", "scripts", "lint.sh")); err != nil {
+		t.Fatalf("script file should be copied with SKILL.md source: %v", err)
+	}
+	st := skill.New(skill.Options{HomeDir: home, ProjectRoot: project, DisableBuiltins: true})
+	sk, ok := st.Read("frontend-design")
+	if !ok || !strings.Contains(sk.Body, "Use crisp layouts.") {
+		t.Fatalf("installed skill should load copied reference, ok=%v body=%q", ok, sk.Body)
+	}
+}
+
+func TestApplyLocalSkillLinkMode(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	src := filepath.Join(project, "local-skills", "gamma.md")
+	writeFile(t, src, "---\nname: gamma\ndescription: Gamma helper\n---\nDo gamma work.")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+		"mode":   "link",
+	})
+
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	if runtime.GOOS == "windows" {
+		t.Skip("symlink semantics differ on Windows")
+	}
+	if resp.Actions[0].Action != "link_skill" {
+		t.Fatalf("action = %q, want link_skill", resp.Actions[0].Action)
+	}
+	if resp.Actions[0].RiskLevel != RiskMedium && resp.Actions[0].RiskLevel != RiskHigh {
+		t.Errorf("link mode should be at least RiskMedium, got %q", resp.Actions[0].RiskLevel)
+	}
+	target := skillInstallPath(home, "gamma", "SKILL.md")
+	if fi, err := os.Lstat(target); err != nil || fi.Mode()&os.ModeSymlink == 0 {
+		t.Fatalf("target should be a symlink: lstat err=%v mode=%v", err, fi.Mode())
+	}
+}
+
+func TestPlanNestedSkillRootRegistersContainingRoots(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	root := filepath.Join(t.TempDir(), "skill-pack")
+	writeFile(t, filepath.Join(root, "top.md"), "---\nname: top\ndescription: Top helper\n---\nbody")
+	writeFile(t, filepath.Join(root, "superpower", "tool-a", "SKILL.md"), "---\nname: tool-a\ndescription: Tool A\n---\nbody")
+	writeFile(t, filepath.Join(root, "superpower", "tool-b", "SKILL.md"), "---\nname: tool-b\ndescription: Tool B\n---\nbody")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": root,
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+	})
+
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	if len(resp.Actions) != 2 {
+		t.Fatalf("actions = %+v, want root and nested containing-root registrations", resp.Actions)
+	}
+	registered := map[string][]string{}
+	for _, a := range resp.Actions {
+		registered[a.Source] = a.Skills
+		if !a.Discoverable || !a.Indexed {
+			t.Fatalf("registered action should be verified: %+v", a)
+		}
+	}
+	if got := strings.Join(registered[root], ","); got != "top" {
+		t.Fatalf("root skills = %q, want top", got)
+	}
+	if got := strings.Join(registered[filepath.Join(root, "superpower")], ","); got != "tool-a,tool-b" {
+		t.Fatalf("nested skills = %q, want tool-a,tool-b", got)
+	}
+	st := skill.New(skill.Options{HomeDir: home, ProjectRoot: project, CustomPaths: registeredRoots(resp.Actions), DisableBuiltins: true})
+	for _, name := range []string{"top", "tool-a", "tool-b"} {
+		if _, ok := st.Read(name); !ok {
+			t.Fatalf("%s should be discoverable after registering containing roots", name)
+		}
+	}
+}
+
+func TestPlanNestedSkillRootRespectsDepthLimit(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	root := filepath.Join(t.TempDir(), "deep-pack")
+	writeFile(t, filepath.Join(root, "one", "two", "three", "deep", "SKILL.md"), "---\nname: deep\ndescription: Deep helper\n---\nbody")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	raw, _ := json.Marshal(map[string]any{
+		"source": root,
+		"kind":   "skill",
+	})
+	out, err := tl.Execute(context.Background(), raw)
+	if err == nil {
+		t.Fatalf("expected no manifest within depth limit, got %s", out)
+	}
+	if !errors.Is(err, ErrManifestMissing) {
+		t.Fatalf("error = %v, want ErrManifestMissing", err)
+	}
+}
+
+func TestApplyLinkSkillRejectsEscape(t *testing.T) {
+	if runtime.GOOS == "windows" {
+		t.Skip("absolute path semantics differ on Windows")
+	}
+	project := t.TempDir()
+	home := t.TempDir()
+
+	// Synthesize a candidate that points at /etc/passwd by calling the
+	// private helper directly. The link check runs before any disk write.
+	if isLinkTargetSafe("/etc/passwd", home, project) {
+		t.Fatal("/etc/passwd should be considered unsafe")
+	}
+	if !isLinkTargetSafe("./local-skill.md", home, project) {
+		t.Fatal("relative link target should be safe")
+	}
+	if !isLinkTargetSafe(filepath.Join(project, "skills/x.md"), home, project) {
+		t.Fatal("link under project root should be safe")
+	}
+
+	src := filepath.Join(t.TempDir(), "escape.md")
+	writeFile(t, src, "---\nname: escape\ndescription: Escape helper\n---\nbody")
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+		"mode":   "link",
+	})
+	if resp.OK {
+		t.Fatalf("unsafe link should fail, got %+v", resp)
+	}
+	if !strings.Contains(resp.Actions[0].Error, ErrUnsafeLinkTarget.Error()) {
+		t.Errorf("error = %q, want ErrUnsafeLinkTarget", resp.Actions[0].Error)
+	}
+}
+
+func TestParseSkillContentStrictAllowsMissingDescription(t *testing.T) {
+	// strict=false lets us install a raw SKILL.md that lacks a description.
+	// The model should still be told the description is empty so the
+	// Skills index entry is honest.
+	cand, err := parseSkillContent("---\nname: raw\n---\nBody without desc", "raw", "in-memory", false)
+	if err != nil {
+		t.Fatalf("strict=false should accept missing description: %v", err)
+	}
+	if cand.Description != "" {
+		t.Errorf("description should be empty, got %q", cand.Description)
+	}
+	if cand.Name != "raw" {
+		t.Errorf("name = %q, want raw", cand.Name)
+	}
+
+	if _, err := parseSkillContent("---\nname: strict\n---\nbody", "strict", "in-memory", true); err == nil {
+		t.Fatal("strict=true should reject missing description")
+	}
+}
+
+func TestApplyStrictFalseWarnsWhenDescriptionMissing(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	src := filepath.Join(t.TempDir(), "raw.md")
+	writeFile(t, src, "---\nname: raw\n---\nBody without desc")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+		"strict": false,
+	})
+
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	if !resp.Actions[0].Discoverable || !resp.Actions[0].Indexed {
+		t.Fatalf("raw skill should still be discoverable/indexed with placeholder: %+v", resp.Actions[0])
+	}
+	found := false
+	for _, warning := range append(resp.Warnings, resp.Actions[0].Warnings...) {
+		if strings.Contains(warning, "no description") {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatalf("warnings = %v action warnings = %v, want missing description warning", resp.Warnings, resp.Actions[0].Warnings)
+	}
+}
+
+// --- plan / apply: MCP paths -----------------------------------------------
+
+func TestPlanLocalMCPJSON(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	mcpPath := filepath.Join(t.TempDir(), ".mcp.json")
+	writeFile(t, mcpPath, `{
+  "mcpServers": {
+    "fs": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] },
+    "remote": { "type": "http", "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${TOKEN}" } }
+  }
+}`)
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": mcpPath,
+		"kind":   "mcp",
+	})
+
+	if !resp.OK || resp.Status != "planned" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if len(resp.Actions) != 2 {
+		t.Fatalf("actions = %+v", resp.Actions)
+	}
+	if resp.Actions[0].Name != "fs" || resp.Actions[0].Transport != "stdio" {
+		t.Fatalf("first action = %+v", resp.Actions[0])
+	}
+	if resp.Actions[1].Name != "remote" || resp.Actions[1].Transport != "http" {
+		t.Fatalf("second action = %+v", resp.Actions[1])
+	}
+	if resp.Kinds.MCP != 2 {
+		t.Errorf("Kinds.MCP = %d, want 2", resp.Kinds.MCP)
+	}
+}
+
+func TestPlanMCPJSONUnknownTierProducesWarning(t *testing.T) {
+	entries, warnings, err := parseMCPJSON([]byte(`{
+  "mcpServers": {
+    "x": { "command": "node", "tier": "absurd" }
+  }
+}`))
+	if err != nil {
+		t.Fatalf("parseMCPJSON: %v", err)
+	}
+	if len(entries) != 1 || entries[0].Tier != "lazy" {
+		t.Fatalf("entries = %+v", entries)
+	}
+	found := false
+	for _, w := range warnings {
+		if strings.Contains(w, "absurd") {
+			found = true
+		}
+	}
+	if !found {
+		t.Errorf("expected warning about unknown tier, got %v", warnings)
+	}
+}
+
+func TestPlanMCPJSONSplitsPastedCommandLine(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	mcpPath := filepath.Join(t.TempDir(), ".mcp.json")
+	writeFile(t, mcpPath, `{
+  "mcpServers": {
+    "playwright": { "command": "npx -y @playwright/mcp" }
+  }
+}`)
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": mcpPath,
+		"kind":   "mcp",
+	})
+
+	if !resp.OK || len(resp.Actions) != 1 {
+		t.Fatalf("response = %+v", resp)
+	}
+	a := resp.Actions[0]
+	if a.Command != "npx" || len(a.Args) != 2 || a.Args[0] != "-y" || a.Args[1] != "@playwright/mcp" {
+		t.Fatalf("action command/args = %q %v, want npx [-y @playwright/mcp]", a.Command, a.Args)
+	}
+	found := false
+	for _, warning := range resp.Warnings {
+		if strings.Contains(warning, "split a pasted MCP command line") {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("warnings = %v, want split warning", resp.Warnings)
+	}
+}
+
+func TestPlanMCPJSONRejectsInvalid(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{"empty", `{"mcpServers": {}}`},
+		{"stdio no command", `{"mcpServers": {"x": {"type": "stdio"}}}`},
+		{"http no url", `{"mcpServers": {"x": {"type": "http"}}}`},
+		{"unknown transport", `{"mcpServers": {"x": {"type": "smoke", "command": "c"}}}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, _, err := parseMCPJSON([]byte(tc.body)); err == nil {
+				t.Fatalf("expected error for %s", tc.name)
+			}
+		})
+	}
+}
+
+func TestApplyRemoteMCPURLConnectsAndPersists(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	stub := &stubConnector{toolCount: 3}
+	tl := NewTool(Options{
+		ProjectRoot: project,
+		HomeDir:     home,
+		ConnectMCP:  stub.connector(),
+	})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source":  "https://mcp.example.com/mcp",
+		"kind":    "mcp",
+		"apply":   true,
+		"scope":   "project",
+		"name":    "example",
+		"headers": map[string]string{"Authorization": "Bearer ${TOKEN}"},
+	})
+
+	if !resp.OK || resp.Status != "done" || resp.Actions[0].ToolCount != 3 {
+		t.Fatalf("response = %+v", resp)
+	}
+	if len(stub.connected) != 1 || stub.connected[0].Name != "example" {
+		t.Fatalf("connected = %+v", stub.connected)
+	}
+	if resp.Actions[0].RiskLevel != RiskHigh {
+		t.Errorf("auth headers should produce RiskHigh, got %q", resp.Actions[0].RiskLevel)
+	}
+	cfg := loadMCPConfigForHome(home)
+	if len(cfg.Plugins) != 1 || cfg.Plugins[0].Headers["Authorization"] != "Bearer ${TOKEN}" {
+		t.Fatalf("plugins = %+v", cfg.Plugins)
+	}
+}
+
+func TestApplyMCPRejectsDuplicateByDefault(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	// Seed an existing entry the same way the first install would have.
+	cfg := loadMCPConfigForHome(home)
+	if err := cfg.UpsertPlugin(config.PluginEntry{Name: "dup", Command: "x"}); err != nil {
+		t.Fatal(err)
+	}
+	saveMCPConfigForHome(t, home, cfg)
+
+	stub := &stubConnector{toolCount: 1, failOnName: "dup"}
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, ConnectMCP: stub.connector()})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://mcp.example.com/mcp",
+		"kind":   "mcp",
+		"apply":  true,
+		"name":   "dup",
+	})
+
+	if resp.OK {
+		t.Fatalf("expected duplicate rejection, got %+v", resp)
+	}
+	if !strings.Contains(resp.Actions[0].Error, "already exists") {
+		t.Errorf("expected ErrAlreadyExists text, got %q", resp.Actions[0].Error)
+	}
+}
+
+func TestApplyMCPReplaceOverwritesExisting(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	cfg := loadMCPConfigForHome(home)
+	if err := cfg.UpsertPlugin(config.PluginEntry{Name: "editable", Command: "old"}); err != nil {
+		t.Fatal(err)
+	}
+	saveMCPConfigForHome(t, home, cfg)
+
+	stub := &stubConnector{toolCount: 1}
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, ConnectMCP: stub.connector()})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source":  "https://mcp.example.com/mcp",
+		"kind":    "mcp",
+		"apply":   true,
+		"replace": true,
+		"name":    "editable",
+	})
+
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	reloaded := loadMCPConfigForHome(home)
+	if reloaded.Plugins[0].Command != "" || reloaded.Plugins[0].URL != "https://mcp.example.com/mcp" {
+		t.Errorf("replace did not update entry: %+v", reloaded.Plugins[0])
+	}
+}
+
+func TestApplyMCPReplaceDisconnectsLiveServerBeforeConnect(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	cfg := loadMCPConfigForHome(home)
+	if err := cfg.UpsertPlugin(config.PluginEntry{Name: "live", Command: "old"}); err != nil {
+		t.Fatal(err)
+	}
+	saveMCPConfigForHome(t, home, cfg)
+
+	var liveConnected atomic.Bool
+	liveConnected.Store(true)
+	var disconnects atomic.Int32
+	var connects atomic.Int32
+	tl := NewTool(Options{
+		ProjectRoot: project,
+		HomeDir:     home,
+		ConnectMCP: func(e config.PluginEntry) (MCPConnectResult, error) {
+			if e.Name == "live" && liveConnected.Load() {
+				return MCPConnectResult{}, errors.New(`server "live" is already connected`)
+			}
+			liveConnected.Store(true)
+			connects.Add(1)
+			return MCPConnectResult{ToolCount: 1, Disconnect: func() { liveConnected.Store(false) }}, nil
+		},
+		OnDisconnect: func(name string) bool {
+			if name != "live" || !liveConnected.Load() {
+				return false
+			}
+			liveConnected.Store(false)
+			disconnects.Add(1)
+			return true
+		},
+	})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source":  "https://mcp.example.com/mcp",
+		"kind":    "mcp",
+		"apply":   true,
+		"replace": true,
+		"name":    "live",
+	})
+
+	if !resp.OK {
+		t.Fatalf("replace should reconnect after disconnecting old live server: %+v", resp)
+	}
+	if disconnects.Load() != 1 || connects.Load() != 1 || !liveConnected.Load() {
+		t.Fatalf("disconnects=%d connects=%d live=%v", disconnects.Load(), connects.Load(), liveConnected.Load())
+	}
+}
+
+func TestApplyMCPRollsBackOnSaveFailure(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	// Make the config readable during loadConfig, then make the file
+	// unwritable so persistence fails after the live MCP connect succeeds.
+	writeFile(t, mcpConfigPathForHome(home), "# empty mcp config\n")
+	if err := os.Chmod(mcpConfigPathForHome(home), 0o400); err != nil {
+		t.Fatal(err)
+	}
+	defer func() {
+		_ = os.Chmod(mcpConfigPathForHome(home), 0o600)
+	}()
+
+	var disconnects atomic.Int32
+	stub := &stubConnector{toolCount: 2, disconnectCalls: &disconnects}
+	tl := NewTool(Options{
+		ProjectRoot: project,
+		HomeDir:     home,
+		ConnectMCP:  stub.connector(),
+		OnDisconnect: func(string) bool {
+			disconnects.Add(1)
+			return true
+		},
+	})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://mcp.example.com/mcp",
+		"kind":   "mcp",
+		"apply":  true,
+		"name":   "ghost",
+	})
+
+	if resp.OK {
+		t.Fatalf("expected failure, got %+v", resp)
+	}
+	if got := disconnects.Load(); got != 1 {
+		t.Errorf("rollback expected to call the new connection Disconnect once, got %d", got)
+	}
+}
+
+func TestApplyConnectFailureDoesNotPersist(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	stub := &stubConnector{failOnName: "broken"}
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, ConnectMCP: stub.connector()})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://mcp.example.com/mcp",
+		"kind":   "mcp",
+		"apply":  true,
+		"name":   "broken",
+	})
+
+	if resp.OK {
+		t.Fatalf("expected connect failure, got %+v", resp)
+	}
+	cfg := loadMCPConfigForHome(home)
+	if len(cfg.Plugins) != 0 {
+		t.Errorf("no plugin should be persisted on connect failure, got %+v", cfg.Plugins)
+	}
+}
+
+func TestPackageActionUsesNpx(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": "@example/mcp-pkg",
+		"kind":   "mcp",
+	})
+
+	if !resp.OK || len(resp.Actions) != 1 {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].Command != "npx" {
+		t.Errorf("command = %q, want npx", resp.Actions[0].Command)
+	}
+	if len(resp.Actions[0].Args) != 2 || resp.Actions[0].Args[0] != "-y" || resp.Actions[0].Args[1] != "@example/mcp-pkg" {
+		t.Errorf("args = %v, want [-y @example/mcp-pkg]", resp.Actions[0].Args)
+	}
+}
+
+func TestPlanURLBlobRewritesToRaw(t *testing.T) {
+	got := rawGitHubBlobURL("https://github.com/foo/bar/blob/main/path/SKILL.md")
+	want := "https://raw.githubusercontent.com/foo/bar/main/path/SKILL.md"
+	if got != want {
+		t.Errorf("rawGitHubBlobURL = %q, want %q", got, want)
+	}
+}
+
+func TestPlanURLRemoteEndpointAuto(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://mcp.example.com/mcp",
+	})
+	if !resp.OK || len(resp.Actions) != 1 {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].Transport != "http" {
+		t.Errorf("transport = %q, want http", resp.Actions[0].Transport)
+	}
+}
+
+func TestPlanURLRemoteMCPHostAuto(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://mcp.stripe.com",
+	})
+	if !resp.OK || len(resp.Actions) != 1 {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].Name != "stripe" || resp.Actions[0].Transport != "http" {
+		t.Errorf("action = %+v, want stripe http", resp.Actions[0])
+	}
+}
+
+func TestPlanURLSSEDefault(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://example.com/sse/stream",
+	})
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].Transport != "sse" {
+		t.Errorf("transport = %q, want sse (URL contains 'sse')", resp.Actions[0].Transport)
+	}
+}
+
+func TestPlanUnsupportedKindReturnsTypedError(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	raw, _ := json.Marshal(map[string]any{
+		"source": "https://example.com/sse/stream",
+		"kind":   "skill",
+	})
+	out, err := tl.Execute(context.Background(), raw)
+	if err == nil {
+		t.Fatalf("expected typed error, got %s", out)
+	}
+	if !errors.Is(err, ErrUnsupportedKind) {
+		t.Errorf("expected ErrUnsupportedKind, got %v", err)
+	}
+}
+
+func TestPlanGitHubRepoProbesMainAndMaster(t *testing.T) {
+	// We can't easily stand up a fake github.com, so we exercise the URL
+	// rewriting and probe selection separately. The hostname check is
+	// `strings.EqualFold(u.Hostname(), "github.com")` — anything else is
+	// treated as a remote URL, not a repo probe.
+	if got := rawGitHubBlobURL("https://github.com/foo/bar/blob/main/path/SKILL.md"); got != "https://raw.githubusercontent.com/foo/bar/main/path/SKILL.md" {
+		t.Errorf("blob rewrite = %q", got)
+	}
+	if got := rawGitHubBlobURL("https://github.com/foo/bar/raw/main/path/SKILL.md"); got != "https://raw.githubusercontent.com/foo/bar/main/path/SKILL.md" {
+		t.Errorf("raw rewrite = %q", got)
+	}
+	if got := rawGitHubBlobURL("https://example.com/foo/bar"); got != "https://example.com/foo/bar" {
+		t.Errorf("non-github passthrough = %q", got)
+	}
+}
+
+func TestPlanGitHubRepoDiscoversMultipleSkills(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+
+	var srv *httptest.Server
+	srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/repos/foo/bar/contents":
+			if r.URL.Query().Get("ref") != "main" {
+				t.Fatalf("ref = %q, want main", r.URL.Query().Get("ref"))
+			}
+			_, _ = fmt.Fprintf(w, `[
+				{"name":"skills","path":"skills","type":"dir"}
+			]`)
+		case "/repos/foo/bar/contents/skills":
+			_, _ = fmt.Fprintf(w, `[
+				{"name":"gsap-core","path":"skills/gsap-core","type":"dir"},
+				{"name":"gsap-timeline","path":"skills/gsap-timeline","type":"dir"}
+			]`)
+		case "/repos/foo/bar/contents/skills/gsap-core":
+			_, _ = fmt.Fprintf(w, `[
+				{"name":"SKILL.md","path":"skills/gsap-core/SKILL.md","type":"file","download_url":%q}
+			]`, srv.URL+"/raw/gsap-core/SKILL.md")
+		case "/repos/foo/bar/contents/skills/gsap-timeline":
+			_, _ = fmt.Fprintf(w, `[
+				{"name":"SKILL.md","path":"skills/gsap-timeline/SKILL.md","type":"file","download_url":%q}
+			]`, srv.URL+"/raw/gsap-timeline/SKILL.md")
+		case "/raw/gsap-core/SKILL.md":
+			_, _ = w.Write([]byte("---\nname: gsap-core\ndescription: GSAP core helper\n---\ncore body"))
+		case "/raw/gsap-timeline/SKILL.md":
+			_, _ = w.Write([]byte("---\nname: gsap-timeline\ndescription: GSAP timeline helper\n---\ntimeline body"))
+		default:
+			http.NotFound(w, r)
+		}
+	}))
+	defer srv.Close()
+	oldAPIBase := githubAPIBaseURL
+	githubAPIBaseURL = srv.URL
+	defer func() { githubAPIBaseURL = oldAPIBase }()
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, HTTPClient: srv.Client()})
+	resp := execInstall(t, tl, map[string]any{
+		"source": "https://github.com/foo/bar",
+		"kind":   "skill",
+	})
+
+	if !resp.OK || resp.Status != "planned" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if len(resp.Actions) != 2 {
+		t.Fatalf("actions = %+v, want two skills", resp.Actions)
+	}
+	if resp.Actions[0].Name != "gsap-core" || resp.Actions[1].Name != "gsap-timeline" {
+		t.Fatalf("actions = %+v", resp.Actions)
+	}
+	for _, action := range resp.Actions {
+		wantSuffix := filepath.Join(action.Name, skill.SkillFile)
+		if action.Layout != "canonical_dir" || !strings.HasSuffix(action.CanonicalPath, wantSuffix) {
+			t.Fatalf("action = %+v, want canonical layout ending in %s", action, wantSuffix)
+		}
+	}
+}
+
+func TestFetchTextAppliesTimeoutAndUA(t *testing.T) {
+	// Use a context with a tiny deadline to assert timeout behavior. We
+	// can't easily test the UA from inside a HandlerFunc, so we just check
+	// that a cancelled context propagates as ErrSourceUnreadable.
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home}).(*installSourceTool)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	_, err := tl.fetchText(ctx, "http://example.invalid")
+	if !errors.Is(err, ErrSourceUnreadable) {
+		t.Errorf("expected ErrSourceUnreadable, got %v", err)
+	}
+}
+
+func TestFetchTextAuthMapsToErrAuthRequired(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer srv.Close()
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, HTTPClient: srv.Client()}).(*installSourceTool)
+	_, err := tl.fetchText(context.Background(), srv.URL)
+	if !errors.Is(err, ErrAuthRequired) {
+		t.Errorf("expected ErrAuthRequired, got %v", err)
+	}
+}
+
+func TestPlanMarkdownSkillURL(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_, _ = w.Write([]byte("---\nname: remote-skill\ndescription: Remote helper\n---\nUse the remote helper."))
+	}))
+	defer srv.Close()
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, HTTPClient: srv.Client()})
+	resp := execInstall(t, tl, map[string]any{
+		"source": srv.URL + "/SKILL.md",
+	})
+
+	if !resp.OK || resp.Status != "planned" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if len(resp.Actions) != 1 || resp.Actions[0].Kind != "skill" || resp.Actions[0].Name != "remote-skill" {
+		t.Fatalf("actions = %+v", resp.Actions)
+	}
+}
+
+// --- uninstall --------------------------------------------------------------
+
+func TestUninstallRemovesSkillByName(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	target := skillInstallPath(home, "doomed.md")
+	writeFile(t, target, "---\nname: doomed\ndescription: Doomed\n---\nbody")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"op":    "uninstall",
+		"name":  "doomed",
+		"scope": "project",
+	})
+
+	if !resp.OK || resp.Status != "done" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if _, err := os.Lstat(target); !errors.Is(err, os.ErrNotExist) {
+		t.Errorf("skill file should be gone, lstat err = %v", err)
+	}
+}
+
+func TestUninstallRemovesRegisteredSkillRootByContainedSkillName(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	root := filepath.Join(t.TempDir(), "shared-skills")
+	writeFile(t, filepath.Join(root, "alpha.md"), "---\nname: alpha\ndescription: Alpha helper\n---\nbody")
+	writeFile(t, filepath.Join(root, "beta.md"), "---\nname: beta\ndescription: Beta helper\n---\nbody")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	install := execInstall(t, tl, map[string]any{
+		"source": root,
+		"kind":   "skill",
+		"apply":  true,
+		"scope":  "project",
+	})
+	if !install.OK {
+		t.Fatalf("install response = %+v", install)
+	}
+
+	resp := execInstall(t, tl, map[string]any{
+		"op":    "uninstall",
+		"name":  "alpha",
+		"scope": "project",
+	})
+	if !resp.OK || resp.Actions[0].Action != "remove_skill_root" {
+		t.Fatalf("uninstall response = %+v", resp)
+	}
+	if resp.Actions[0].SkillCount != 2 {
+		t.Errorf("SkillCount = %d, want 2", resp.Actions[0].SkillCount)
+	}
+	cfg := loadSkillsConfigForHome(home)
+	if len(cfg.Skills.Paths) != 0 {
+		t.Fatalf("skills.paths should be empty after root uninstall, got %v", cfg.Skills.Paths)
+	}
+}
+
+func TestUninstallRemovesMCPAndDisconnects(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	cfg := loadMCPConfigForHome(home)
+	if err := cfg.UpsertPlugin(config.PluginEntry{Name: "ed", Type: "http", URL: "https://mcp.example.com/mcp"}); err != nil {
+		t.Fatal(err)
+	}
+	saveMCPConfigForHome(t, home, cfg)
+
+	var disconnects atomic.Int32
+	tl := NewTool(Options{
+		ProjectRoot: project,
+		HomeDir:     home,
+		OnDisconnect: func(string) bool {
+			disconnects.Add(1)
+			return true
+		},
+	})
+	resp := execInstall(t, tl, map[string]any{
+		"op":    "uninstall",
+		"name":  "ed",
+		"scope": "project",
+	})
+
+	if !resp.OK {
+		t.Fatalf("response = %+v", resp)
+	}
+	if disconnects.Load() != 1 {
+		t.Errorf("OnDisconnect should fire once, got %d", disconnects.Load())
+	}
+	reloaded := loadMCPConfigForHome(home)
+	if len(reloaded.Plugins) != 0 {
+		t.Errorf("plugin should be removed, got %+v", reloaded.Plugins)
+	}
+}
+
+func TestUninstallUnknownNameIsBlocked(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"op":   "uninstall",
+		"name": "ghost",
+	})
+	if resp.OK || resp.Status != "blocked" {
+		t.Fatalf("response = %+v", resp)
+	}
+}
+
+func TestUninstallRequiresName(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	raw, _ := json.Marshal(map[string]any{"op": "uninstall"})
+	if _, err := tl.Execute(context.Background(), raw); err == nil {
+		t.Fatal("expected error when name is missing for uninstall")
+	}
+}
+
+// --- approval hook ----------------------------------------------------------
+
+func TestApprovalHookDeniesApply(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	src := filepath.Join(t.TempDir(), "zeta.md")
+	writeFile(t, src, "---\nname: zeta\ndescription: Zeta helper\n---\nbody")
+
+	var seen []action
+	tl := NewTool(Options{
+		ProjectRoot: project,
+		HomeDir:     home,
+		Approval: func(actions []action) error {
+			seen = actions
+			return errors.New("user said no")
+		},
+	})
+
+	resp := execInstall(t, tl, map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+	})
+	if resp.OK {
+		t.Fatalf("expected denial, got %+v", resp)
+	}
+	if resp.Status != "denied" {
+		t.Errorf("status = %q, want denied", resp.Status)
+	}
+	if len(seen) != 1 || seen[0].Name != "zeta" {
+		t.Errorf("approval should see the planned actions, got %+v", seen)
+	}
+}
+
+func TestPlanIDMismatchRefusesApply(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	src := filepath.Join(t.TempDir(), "eta.md")
+	writeFile(t, src, "---\nname: eta\ndescription: Eta helper\n---\nbody")
+
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	raw, _ := json.Marshal(map[string]any{
+		"source": src,
+		"kind":   "skill",
+		"apply":  true,
+		"planId": "sha256:00000000000000000000000000000000",
+	})
+	out, err := tl.Execute(context.Background(), raw)
+	if err == nil {
+		t.Fatalf("expected planId mismatch error, got %s", out)
+	}
+	if !errors.Is(err, ErrApprovalDenied) {
+		t.Errorf("expected ErrApprovalDenied, got %v", err)
+	}
+}
+
+func TestPlanIDIncludesActionDetails(t *testing.T) {
+	req := request{
+		Op:     "install",
+		Source: "/tmp/example/.mcp.json",
+		Kind:   "mcp",
+		Scope:  "project",
+		Mode:   "auto",
+	}
+	a := action{Kind: "mcp", Action: "install_mcp_server", Name: "same", URL: "https://mcp.one.example/mcp", Transport: "http", ConfigPath: "/repo/reasonix.toml"}
+	b := a
+	b.URL = "https://mcp.two.example/mcp"
+	if computePlanID(req, []action{a}) == computePlanID(req, []action{b}) {
+		t.Fatal("planId should change when action URL changes")
+	}
+}
+
+// --- sanitizers / parsers ---------------------------------------------------
+
+func TestSanitizeNameEdges(t *testing.T) {
+	cases := map[string]string{
+		"":                       "mcp",
+		"   ":                    "mcp",
+		"@@leading":              "leading",    // leading @ is stripped before the prefix rule
+		"_underscore":            "underscore", // config requires [a-zA-Z0-9] as first char
+		"foo bar baz":            "foo-bar-baz",
+		"foo/bar":                "foo-bar",
+		"FOO":                    "foo",
+		"a.b-c_d":                "a.b-c_d",
+		strings.Repeat("x", 100): strings.Repeat("x", 64),
+	}
+	for in, want := range cases {
+		if got := sanitizeName(in); got != want {
+			t.Errorf("sanitizeName(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestMCPNameFromURL(t *testing.T) {
+	cases := map[string]string{
+		"https://mcp.stripe.com/mcp":        "stripe",
+		"https://api.example.com/mcp":       "example",
+		"https://www.foo.com/mcp":           "foo",
+		"http://localhost:3000/mcp":         "local-3000",
+		"https://mcp.example.co.uk/agent":   "example",
+		"https://api.mcp.openai.com/v1/mcp": "openai",
+	}
+	for in, want := range cases {
+		if got := mcpNameFromURL(in); got != want {
+			t.Errorf("mcpNameFromURL(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestValidateMCPEntry(t *testing.T) {
+	if err := validateMCPEntry(config.PluginEntry{Name: "x", Command: "y"}); err != nil {
+		t.Errorf("stdio with command should validate, got %v", err)
+	}
+	if err := validateMCPEntry(config.PluginEntry{Name: "x", Type: "http", URL: "http://x"}); err != nil {
+		t.Errorf("http with url should validate, got %v", err)
+	}
+	if err := validateMCPEntry(config.PluginEntry{Name: ""}); err == nil {
+		t.Error("empty name should fail")
+	}
+	if err := validateMCPEntry(config.PluginEntry{Name: "x", Type: "carrier-pigeon", Command: "c"}); err == nil {
+		t.Error("unknown transport should fail")
+	}
+}
+
+func TestComputePlanIDStable(t *testing.T) {
+	req := request{Op: "install", Source: "x", Scope: "project", Kind: "skill"}
+	actions := []action{{Kind: "skill", Name: "a", Action: "copy_skill"}}
+	id1 := computePlanID(req, actions)
+	id2 := computePlanID(req, actions)
+	if id1 != id2 {
+		t.Errorf("planId should be stable, got %q vs %q", id1, id2)
+	}
+	id3 := computePlanID(request{Op: "install", Source: "y", Scope: "project", Kind: "skill"}, actions)
+	if id3 == id1 {
+		t.Errorf("planId should change with source")
+	}
+}
+
+// --- local executable -------------------------------------------------------
+
+func TestPlanLocalExecutableDetected(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	bin := filepath.Join(t.TempDir(), "bin")
+	if err := os.MkdirAll(bin, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	exe := writeLocalExecutable(t, bin, "mcp-x")
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home})
+	resp := execInstall(t, tl, map[string]any{
+		"source": exe,
+		"kind":   "mcp",
+	})
+	if !resp.OK || len(resp.Actions) != 1 {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].Command != exe {
+		t.Errorf("command = %q, want the executable path", resp.Actions[0].Command)
+	}
+}
+
+func TestApplyLocalExecutableHonorsCommandOverride(t *testing.T) {
+	project := t.TempDir()
+	home := t.TempDir()
+	bin := filepath.Join(t.TempDir(), "bin")
+	if err := os.MkdirAll(bin, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	server := writeLocalExecutable(t, bin, "server")
+
+	stub := &stubConnector{toolCount: 1}
+	tl := NewTool(Options{ProjectRoot: project, HomeDir: home, ConnectMCP: stub.connector()})
+	resp := execInstall(t, tl, map[string]any{
+		"source":  server,
+		"kind":    "mcp",
+		"apply":   true,
+		"name":    "wrapped",
+		"command": "node",
+		"args":    []string{server},
+	})
+
+	if !resp.OK || len(resp.Actions) != 1 {
+		t.Fatalf("response = %+v", resp)
+	}
+	if resp.Actions[0].Command != "node" || len(resp.Actions[0].Args) != 1 || resp.Actions[0].Args[0] != server {
+		t.Fatalf("action command/args = %q %v, want node [%s]", resp.Actions[0].Command, resp.Actions[0].Args, server)
+	}
+	if len(stub.connected) != 1 || stub.connected[0].Command != "node" || len(stub.connected[0].Args) != 1 || stub.connected[0].Args[0] != server {
+		t.Fatalf("connected entry = %+v, want node [%s]", stub.connected, server)
+	}
+	cfg := loadMCPConfigForHome(home)
+	if len(cfg.Plugins) != 1 || cfg.Plugins[0].Command != "node" || len(cfg.Plugins[0].Args) != 1 || cfg.Plugins[0].Args[0] != server {
+		t.Fatalf("persisted plugins = %+v, want node [%s]", cfg.Plugins, server)
+	}
+}
+
+func writeLocalExecutable(t *testing.T, dir, name string) string {
+	t.Helper()
+	if runtime.GOOS == "windows" {
+		path := filepath.Join(dir, name+".cmd")
+		writeFile(t, path, "@echo off\r\nexit /b 0\r\n")
+		return path
+	}
+	path := filepath.Join(dir, name)
+	writeFile(t, path, "#!/bin/sh\nexit 0\n")
+	if err := os.Chmod(path, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// --- plan-only: RiskLevel surfacing -----------------------------------------
+
+func TestLinkRiskIsMedium(t *testing.T) {
+	if level, _ := skillActionRisk("link", skillCandidate{SourcePath: "x"}); level != RiskMedium {
+		t.Errorf("link mode should be RiskMedium, got %q", level)
+	}
+	if level, _ := skillActionRisk("copy", skillCandidate{SourcePath: "x"}); level != RiskLow {
+		t.Errorf("copy mode should be RiskLow, got %q", level)
+	}
+}
+
+func TestEagerTierEscalatesRisk(t *testing.T) {
+	level, _ := mcpActionRisk(config.PluginEntry{Name: "x", Tier: "eager", URL: "http://x"}, nil)
+	if level != RiskHigh {
+		t.Errorf("eager tier should escalate to RiskHigh, got %q", level)
+	}
+}
+
+// --- helpers ----------------------------------------------------------------
+
+// ExampleNewTool is a godoc example that exercises the public surface
+// without touching the filesystem. It also serves as smoke coverage that
+// the Schema() output is valid JSON and the tool does not panic on a
+// well-formed call.
+func ExampleNewTool() {
+	tl := NewTool(Options{
+		ProjectRoot: "/tmp/example",
+		HomeDir:     "/tmp/example-home",
+	})
+	raw, _ := json.Marshal(map[string]any{"source": "https://example.com/mcp"})
+	out, _ := tl.Execute(context.Background(), raw)
+	var resp response
+	_ = json.Unmarshal([]byte(out), &resp)
+	fmt.Printf("status=%s kind=%s skill=%d mcp=%d\n",
+		resp.Status, resp.Kind, resp.Kinds.Skill, resp.Kinds.MCP)
+	// Output: status=planned kind=mcp skill=0 mcp=1
+}
diff --git a/internal/installsource/mcp.go b/internal/installsource/mcp.go
new file mode 100644
index 000000000..738641355
--- /dev/null
+++ b/internal/installsource/mcp.go
@@ -0,0 +1,266 @@
+package installsource
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"reasonix/internal/config"
+)
+
+// mcpEntryAction assembles the DTO for a single MCP server install. The
+// caller decides whether apply=true actually runs cfg.UpsertPlugin +
+// SaveTo + connectMCP.
+func (t *installSourceTool) mcpEntryAction(req request, e config.PluginEntry, source string) action {
+	var normalizedCommand bool
+	e, normalizedCommand = config.NormalizePluginCommandLine(e)
+	// Tier comes from the call (req.Tier) or the entry; either way we
+	// validate. An unrecognised tier is silently downgraded to "lazy" by
+	// normalizeTier — we capture the original value to surface a warning.
+	desired := firstNonEmpty(req.Tier, e.Tier)
+	norm, ok := normalizeTier(desired)
+	e.Tier = norm
+	a := action{
+		Kind:       "mcp",
+		Action:     "install_mcp_server",
+		Name:       e.Name,
+		Source:     source,
+		ConfigPath: t.mcpConfigPath(req.Scope),
+		Scope:      req.Scope,
+		Transport:  pluginTransport(e),
+		URL:        e.URL,
+		Command:    e.Command,
+		Args:       e.Args,
+		Env:        e.Env,
+		Headers:    e.Headers,
+		entry:      e,
+	}
+	if !ok && strings.TrimSpace(desired) != "" {
+		a.RiskReasons = append(a.RiskReasons, fmt.Sprintf("tier %q is unknown; treating as lazy", desired))
+	}
+	if normalizedCommand {
+		a.RiskReasons = append(a.RiskReasons, "split a pasted MCP command line into command and args")
+	}
+	a.RiskLevel, a.RiskReasons = mcpActionRisk(e, a.RiskReasons)
+	return a
+}
+
+// mcpActionRisk classifies a single MCP install. An entry with auth headers,
+// an `eager` tier, or a package-name source is medium. An entry with auth
+// material and an out-of-tree URL is high.
+func mcpActionRisk(e config.PluginEntry, reasons []string) (RiskLevel, []string) {
+	level := RiskMedium
+	hasAuth := false
+	for k, v := range e.Headers {
+		if strings.EqualFold(k, "Authorization") || strings.Contains(strings.ToLower(v), "bearer") || strings.Contains(strings.ToLower(v), "token") {
+			hasAuth = true
+			reasons = append(reasons, "sends auth headers to "+e.URL)
+		}
+	}
+	if e.Tier == "eager" {
+		level = RiskHigh
+		reasons = append(reasons, "tier=eager blocks startup until the handshake completes")
+	}
+	if hasAuth && level == RiskMedium {
+		level = RiskHigh
+	}
+	return level, reasons
+}
+
+// remoteMCPAction builds a server entry from a URL alone. The default
+// transport is http unless the URL's path smells like SSE.
+func (t *installSourceTool) remoteMCPAction(req request, sourceURL string) action {
+	transport := req.Transport
+	if transport == "" || transport == "auto" {
+		transport = "http"
+		if strings.Contains(strings.ToLower(sourceURL), "sse") {
+			transport = "sse"
+		}
+	}
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		name = mcpNameFromURL(sourceURL)
+	}
+	e := config.PluginEntry{
+		Name:    name,
+		Type:    transport,
+		URL:     sourceURL,
+		Headers: cleanMap(req.Headers),
+		Tier:    req.Tier,
+	}
+	return t.mcpEntryAction(req, e, sourceURL)
+}
+
+// localExecutableMCPAction treats a chmod +x'd local file as a stdio MCP
+// server. By default the file itself becomes the command; callers may override
+// the command to wrap the source with an interpreter.
+func (t *installSourceTool) localExecutableMCPAction(req request, path string) action {
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		name = sanitizeName(strings.TrimSuffix(filepath.Base(path), filepath.Ext(path)))
+	}
+	command := strings.TrimSpace(req.Command)
+	if command == "" {
+		command = path
+	}
+	e := config.PluginEntry{
+		Name:    name,
+		Command: command,
+		Args:    append([]string(nil), req.Args...),
+		Env:     cleanMap(req.Env),
+		Tier:    req.Tier,
+	}
+	return t.mcpEntryAction(req, e, path)
+}
+
+// packageMCPAction treats the source as an npm package name and constructs
+// the canonical `npx -y <pkg>` invocation. The caller can override the
+// command and args for non-npm package sources.
+func (t *installSourceTool) packageMCPAction(req request) action {
+	name := strings.TrimSpace(req.Name)
+	if name == "" {
+		name = sanitizeName(strings.TrimPrefix(req.Source, "@"))
+		if i := strings.LastIndex(name, "/"); i >= 0 {
+			name = name[i+1:]
+		}
+	}
+	command := strings.TrimSpace(req.Command)
+	args := append([]string(nil), req.Args...)
+	if command == "" {
+		command = "npx"
+		args = []string{"-y", req.Source}
+	}
+	e := config.PluginEntry{
+		Name:    name,
+		Command: command,
+		Args:    args,
+		Env:     cleanMap(req.Env),
+		Tier:    req.Tier,
+	}
+	return t.mcpEntryAction(req, e, req.Source)
+}
+
+// readMCPJSON reads a .mcp.json file from disk and parses it. It is a
+// convenience wrapper used by planLocal; the parser itself is exported as
+// parseMCPJSON for tests.
+func readMCPJSON(path string) ([]config.PluginEntry, []string, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return nil, nil, err
+	}
+	entries, warnings, err := parseMCPJSON(b)
+	if err != nil {
+		return nil, warnings, err
+	}
+	return entries, warnings, nil
+}
+
+// parseMCPJSON extracts mcpServers entries from a .mcp.json-style document.
+// Warnings are returned for non-fatal anomalies (unknown tier values) and
+// collected separately so a typo does not refuse an otherwise valid file.
+func parseMCPJSON(b []byte) ([]config.PluginEntry, []string, error) {
+	var raw struct {
+		MCPServers map[string]struct {
+			Type      string            `json:"type"`
+			Command   string            `json:"command"`
+			Args      []string          `json:"args"`
+			Env       map[string]string `json:"env"`
+			URL       string            `json:"url"`
+			Headers   map[string]string `json:"headers"`
+			AutoStart *bool             `json:"auto_start"`
+			Tier      string            `json:"tier"`
+		} `json:"mcpServers"`
+	}
+	if err := json.Unmarshal(b, &raw); err != nil {
+		return nil, nil, newErr(ErrInvalidManifest, "could not parse .mcp.json: %v", err)
+	}
+	if len(raw.MCPServers) == 0 {
+		return nil, nil, newErr(ErrManifestMissing, ".mcp.json has no mcpServers")
+	}
+	names := make([]string, 0, len(raw.MCPServers))
+	for name := range raw.MCPServers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	out := make([]config.PluginEntry, 0, len(names))
+	var warnings []string
+	for _, name := range names {
+		s := raw.MCPServers[name]
+		// Validate the raw transport before normalizeTransport gets a
+		// chance to silently map an unknown value to "auto"/"stdio".
+		rawType := strings.ToLower(strings.TrimSpace(s.Type))
+		if rawType != "" && rawType != "stdio" && rawType != "http" && rawType != "sse" && rawType != "streamable-http" {
+			return nil, warnings, newErr(ErrInvalidManifest, "MCP server %q has unknown transport %q", name, s.Type)
+		}
+		typ := normalizeTransport(s.Type)
+		if typ == "auto" {
+			if strings.TrimSpace(s.URL) != "" {
+				typ = "http"
+			} else {
+				typ = "stdio"
+			}
+		}
+		tier, ok := normalizeTier(s.Tier)
+		if !ok && strings.TrimSpace(s.Tier) != "" {
+			warnings = append(warnings, fmt.Sprintf("%s: tier %q is unknown; treating as lazy", name, s.Tier))
+		}
+		e := config.PluginEntry{
+			Name:      name,
+			Type:      typ,
+			Command:   strings.TrimSpace(s.Command),
+			Args:      append([]string(nil), s.Args...),
+			Env:       cleanMap(s.Env),
+			URL:       strings.TrimSpace(s.URL),
+			Headers:   cleanMap(s.Headers),
+			AutoStart: s.AutoStart,
+			Tier:      tier,
+		}
+		// An empty Type is the canonical "stdio" form; keep it that way so
+		// the rest of the config layer (UpsertPlugin / ShouldAutoStart)
+		// can treat "" and "stdio" identically.
+		if e.Type == "stdio" {
+			e.Type = ""
+		}
+		normalized, changed := config.NormalizePluginCommandLine(e)
+		e = normalized
+		if changed {
+			warnings = append(warnings, fmt.Sprintf("%s: split a pasted MCP command line into command and args", name))
+		}
+		if err := validateMCPEntry(e); err != nil {
+			return nil, warnings, err
+		}
+		out = append(out, e)
+	}
+	return out, warnings, nil
+}
+
+// validateMCPEntry enforces the per-transport required fields. It is the
+// last line of defense before a server entry is persisted.
+func validateMCPEntry(e config.PluginEntry) error {
+	if strings.TrimSpace(e.Name) == "" {
+		return newErr(ErrInvalidManifest, "MCP server name is required")
+	}
+	// Reject explicit unknown transports. Without this check, normalizeTransport
+	// would silently map "carrier-pigeon" -> "auto" -> "stdio" and the entry
+	// would be persisted with the wrong effective type.
+	rawType := strings.ToLower(strings.TrimSpace(e.Type))
+	if rawType != "" && rawType != "stdio" && rawType != "http" && rawType != "sse" {
+		return newErr(ErrInvalidManifest, "MCP server %q has unknown transport %q", e.Name, e.Type)
+	}
+	switch pluginTransport(e) {
+	case "stdio":
+		if strings.TrimSpace(e.Command) == "" {
+			return newErr(ErrInvalidManifest, "MCP server %q is stdio but has no command", e.Name)
+		}
+	case "http", "sse":
+		if strings.TrimSpace(e.URL) == "" {
+			return newErr(ErrInvalidManifest, "MCP server %q is remote but has no url", e.Name)
+		}
+	default:
+		return newErr(ErrInvalidManifest, "MCP server %q has unknown transport %q", e.Name, e.Type)
+	}
+	return nil
+}
diff --git a/internal/installsource/names.go b/internal/installsource/names.go
new file mode 100644
index 000000000..b9218a880
--- /dev/null
+++ b/internal/installsource/names.go
@@ -0,0 +1,285 @@
+package installsource
+
+import (
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"runtime"
+	"strings"
+
+	"reasonix/internal/config"
+)
+
+// packageNameRe matches valid npm package-name segments. Pinned by [a-z0-9._-]
+// — exactly what npm allows. The leading character may be a digit (scoped
+// packages like @5/test are rare but valid).
+var packageNameRe = regexp.MustCompile(`^[a-zA-Z0-9._-]+$`)
+
+func isURL(s string) bool {
+	u, err := url.Parse(s)
+	return err == nil && (u.Scheme == "http" || u.Scheme == "https") && u.Host != ""
+}
+
+func looksLikeMarkdownURL(s string) bool {
+	u, err := url.Parse(s)
+	if err != nil {
+		return false
+	}
+	return strings.EqualFold(filepath.Ext(u.Path), ".md")
+}
+
+func looksLikeMCPJSONURL(s string) bool {
+	u, err := url.Parse(s)
+	if err != nil {
+		return false
+	}
+	return strings.EqualFold(filepath.Base(u.Path), ".mcp.json")
+}
+
+// looksLikeRemoteMCPEndpoint is a loose heuristic: any URL with "mcp" or
+// "sse" in its path, or a host that clearly advertises mcp, is treated as a
+// remote MCP endpoint when no manifest could be downloaded. Used as a fallback
+// for the auto-resolver; users can always set kind="mcp" to bypass the guess.
+func looksLikeRemoteMCPEndpoint(s string) bool {
+	u, err := url.Parse(s)
+	if err != nil {
+		return false
+	}
+	host := strings.ToLower(u.Hostname())
+	if strings.HasPrefix(host, "mcp.") || strings.HasPrefix(host, "mcp-") || strings.Contains(host, ".mcp.") || strings.Contains(host, "-mcp.") {
+		return true
+	}
+	p := strings.ToLower(u.Path)
+	return strings.Contains(p, "mcp") || strings.Contains(p, "sse")
+}
+
+// rawGitHubBlobURL rewrites github.com/<owner>/<repo>/blob/<ref>/<path> (and
+// the /raw/ variant) into the raw.githubusercontent.com form. Other URLs are
+// returned untouched so we don't corrupt non-github sources.
+func rawGitHubBlobURL(s string) string {
+	u, err := url.Parse(s)
+	if err != nil || !strings.EqualFold(u.Hostname(), "github.com") {
+		return s
+	}
+	parts := strings.Split(strings.Trim(u.Path, "/"), "/")
+	if len(parts) >= 5 && parts[2] == "blob" {
+		return "https://raw.githubusercontent.com/" + parts[0] + "/" + parts[1] + "/" + parts[3] + "/" + strings.Join(parts[4:], "/")
+	}
+	if len(parts) >= 5 && parts[2] == "raw" {
+		return "https://raw.githubusercontent.com/" + parts[0] + "/" + parts[1] + "/" + parts[3] + "/" + strings.Join(parts[4:], "/")
+	}
+	return s
+}
+
+func looksLikePackage(s string) bool {
+	if strings.ContainsAny(s, " \t\n\\") || strings.HasPrefix(s, ".") || strings.HasPrefix(s, "/") {
+		return false
+	}
+	if strings.HasPrefix(s, "@") {
+		parts := strings.Split(s, "/")
+		return len(parts) == 2 && packageNameRe.MatchString(parts[0][1:]) && packageNameRe.MatchString(parts[1])
+	}
+	return packageNameRe.MatchString(s)
+}
+
+// isExecutable reports whether path is a regular executable file. POSIX uses
+// execute bits; Windows uses executable file extensions because chmod bits do
+// not reliably model launchability there.
+func isExecutable(path string, info os.FileInfo) bool {
+	if !info.Mode().IsRegular() {
+		return false
+	}
+	if runtime.GOOS == "windows" {
+		switch strings.ToLower(filepath.Ext(path)) {
+		case ".exe", ".cmd", ".bat", ".ps1":
+			return true
+		}
+	}
+	return info.Mode().Perm()&0o111 != 0
+}
+
+// nameFromURL produces a stable human-readable skill name from a URL's
+// filename stem. Falls back to "skill" when the URL has no name component.
+func nameFromURL(s string) string {
+	u, err := url.Parse(s)
+	if err != nil {
+		return "skill"
+	}
+	base := filepath.Base(u.Path)
+	if ext := filepath.Ext(base); ext != "" {
+		base = strings.TrimSuffix(base, ext)
+	}
+	return sanitizeName(base)
+}
+
+// mcpNameFromURL derives a default MCP server name from a remote URL. It
+// strips common subdomains and TLDs so e.g. mcp.stripe.com -> "stripe" and
+// api.example.co -> "example". localhost:port and explicit names work too.
+func mcpNameFromURL(s string) string {
+	u, err := url.Parse(s)
+	if err != nil || u.Hostname() == "" {
+		return "mcp"
+	}
+	host := strings.ToLower(u.Hostname())
+	if host == "localhost" || host == "127.0.0.1" || host == "::1" {
+		// Distinguish local servers by port; "localhost" alone is unhelpful.
+		if p := u.Port(); p != "" {
+			return sanitizeName("local-" + p)
+		}
+		return "local"
+	}
+	// Strip "mcp.", "api.", "www." subdomains and any "mcp-" / "mcp_" prefix.
+	for _, p := range []string{"mcp.", "api.", "www."} {
+		host = strings.TrimPrefix(host, p)
+	}
+	host = strings.TrimPrefix(host, "mcp-")
+	host = strings.TrimPrefix(host, "mcp_")
+	// Drop the TLD and any common second-level TLDs ("co.uk", "com.au").
+	parts := strings.Split(host, ".")
+	switch len(parts) {
+	case 0, 1:
+		return sanitizeName(host)
+	case 2:
+		return sanitizeName(parts[0])
+	default:
+		// Two-letter final segment is likely a ccTLD paired with a SLD
+		// (".co.uk", ".com.au", ".co.jp"). Use the third-to-last.
+		if len(parts[len(parts)-1]) == 2 {
+			return sanitizeName(parts[len(parts)-3])
+		}
+		return sanitizeName(parts[len(parts)-2])
+	}
+}
+
+// sanitizeName produces a valid skill/MCP identifier. Letters, digits, _ . -
+// are kept; everything else becomes a single dash. Leading non-alphanumerics
+// get an "mcp-" prefix so the result is always a valid config key.
+func sanitizeName(s string) string {
+	s = strings.TrimSpace(strings.ToLower(s))
+	s = strings.TrimPrefix(s, "@")
+	s = strings.ReplaceAll(s, "/", "-")
+	var b strings.Builder
+	prevDash := false
+	for _, r := range s {
+		ok := (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '_' || r == '.' || r == '-'
+		if !ok {
+			if !prevDash {
+				b.WriteByte('-')
+				prevDash = true
+			}
+			continue
+		}
+		b.WriteRune(r)
+		prevDash = r == '-'
+	}
+	out := strings.Trim(b.String(), "-._")
+	if out == "" {
+		return "mcp"
+	}
+	if !((out[0] >= 'a' && out[0] <= 'z') || (out[0] >= '0' && out[0] <= '9')) {
+		out = "mcp-" + out
+	}
+	if len(out) > 64 {
+		out = out[:64]
+		out = strings.TrimRight(out, "-._")
+	}
+	return out
+}
+
+// cleanMap drops empty keys. A nil/empty input returns nil so the JSON shape
+// stays compact and downstream config compares equal.
+func cleanMap(in map[string]string) map[string]string {
+	if len(in) == 0 {
+		return nil
+	}
+	out := map[string]string{}
+	for k, v := range in {
+		k = strings.TrimSpace(k)
+		if k != "" {
+			out[k] = v
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func collapseSpaces(s string) string { return strings.Join(strings.Fields(s), " ") }
+
+func firstNonEmpty(vs ...string) string {
+	for _, v := range vs {
+		if strings.TrimSpace(v) != "" {
+			return strings.TrimSpace(v)
+		}
+	}
+	return ""
+}
+
+func normalizeKind(kind string) string {
+	switch strings.ToLower(strings.TrimSpace(kind)) {
+	case "skill", "mcp":
+		return strings.ToLower(strings.TrimSpace(kind))
+	default:
+		return "auto"
+	}
+}
+
+func normalizeMode(mode string) string {
+	switch strings.ToLower(strings.TrimSpace(mode)) {
+	case "copy", "link", "register":
+		return strings.ToLower(strings.TrimSpace(mode))
+	default:
+		return "auto"
+	}
+}
+
+func modeForSingleSkill(mode string) string {
+	if mode == "link" {
+		return mode
+	}
+	return "copy"
+}
+
+func normalizeTransport(t string) string {
+	switch strings.ToLower(strings.TrimSpace(t)) {
+	case "http", "streamable-http":
+		return "http"
+	case "sse":
+		return "sse"
+	case "stdio":
+		return "stdio"
+	default:
+		return "auto"
+	}
+}
+
+// normalizeTier maps a tier value into a known set. The boolean returned
+// reports whether the original value was already in the set; callers use it
+// to surface a warning when a typo'd tier quietly becomes "lazy".
+func normalizeTier(tier string) (string, bool) {
+	switch strings.ToLower(strings.TrimSpace(tier)) {
+	case "eager":
+		return "eager", true
+	case "background":
+		return "background", true
+	case "", "lazy":
+		return "lazy", true
+	default:
+		return "lazy", false
+	}
+}
+
+// pluginTransport reports the effective transport for a plugin entry,
+// normalizing empty Type to stdio (the default the config layer expects).
+func pluginTransport(e config.PluginEntry) string {
+	switch normalizeTransport(e.Type) {
+	case "http":
+		return "http"
+	case "sse":
+		return "sse"
+	default:
+		return "stdio"
+	}
+}
diff --git a/internal/installsource/plan.go b/internal/installsource/plan.go
new file mode 100644
index 000000000..3d5903868
--- /dev/null
+++ b/internal/installsource/plan.go
@@ -0,0 +1,440 @@
+package installsource
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"reasonix/internal/skill"
+)
+
+var githubAPIBaseURL = "https://api.github.com"
+
+// plan turns a request into a list of actions plus a warnings slice. It
+// does not touch the disk; the apply phase is responsible for side effects.
+func (t *installSourceTool) plan(ctx context.Context, req request) ([]action, []string, error) {
+	if isURL(req.Source) {
+		return t.planURL(ctx, req)
+	}
+	path := t.resolvePath(req.Source)
+	if info, err := os.Stat(path); err == nil {
+		return t.planLocal(req, path, info)
+	}
+	if req.Kind == "auto" || req.Kind == "mcp" {
+		if looksLikePackage(req.Source) {
+			return []action{t.packageMCPAction(req)}, nil, nil
+		}
+	}
+	return nil, nil, newErr(ErrSourceUnreadable, "source %q is not a readable local path, URL, or supported package name", req.Source)
+}
+
+func (t *installSourceTool) planURL(ctx context.Context, req request) ([]action, []string, error) {
+	rawURL := rawGitHubBlobURL(req.Source)
+	if req.Kind == "mcp" && !looksLikeMarkdownURL(rawURL) && !looksLikeMCPJSONURL(rawURL) {
+		return []action{t.remoteMCPAction(req, rawURL)}, nil, nil
+	}
+	if looksLikeMarkdownURL(rawURL) || looksLikeMCPJSONURL(rawURL) || rawURL != req.Source {
+		actions, warnings, err := t.planDownloadedURL(ctx, req, rawURL)
+		if err == nil && len(actions) > 0 {
+			return actions, warnings, nil
+		}
+		if req.Kind != "auto" {
+			return nil, warnings, err
+		}
+	}
+	if gitActions, warnings := t.tryGitHubRepo(ctx, req); len(gitActions) > 0 {
+		return gitActions, warnings, nil
+	}
+	if req.Kind == "skill" {
+		return nil, nil, newErr(ErrUnsupportedKind, "URL %q is not a direct markdown skill file or GitHub SKILL.md", req.Source)
+	}
+	if req.Kind == "auto" && !looksLikeRemoteMCPEndpoint(req.Source) {
+		return nil, nil, newErr(ErrUnsupportedKind, "URL %q is not a direct MCP endpoint or skill manifest; provide a raw SKILL.md, .mcp.json, or use kind='mcp' for a remote MCP endpoint", req.Source)
+	}
+	return []action{t.remoteMCPAction(req, req.Source)}, nil, nil
+}
+
+func (t *installSourceTool) planDownloadedURL(ctx context.Context, req request, sourceURL string) ([]action, []string, error) {
+	body, err := t.fetchText(ctx, sourceURL)
+	if err != nil {
+		return nil, nil, err
+	}
+	if req.Kind == "auto" || req.Kind == "mcp" {
+		entries, warnings, err := parseMCPJSON([]byte(body))
+		if err == nil && len(entries) > 0 {
+			actions := make([]action, 0, len(entries))
+			for _, e := range entries {
+				actions = append(actions, t.mcpEntryAction(req, e, sourceURL))
+			}
+			return actions, warnings, nil
+		}
+	}
+	if req.Kind == "auto" || req.Kind == "skill" {
+		name := strings.TrimSpace(req.Name)
+		if name == "" {
+			name = nameFromURL(sourceURL)
+		}
+		cand, err := parseSkillContent(body, name, sourceURL, req.strict())
+		if err == nil {
+			return []action{t.skillAction(req, cand, "copy")}, nil, nil
+		}
+		return nil, nil, err
+	}
+	return nil, nil, newErr(ErrUnsupportedKind, "downloaded URL did not contain a requested %s install source", req.Kind)
+}
+
+func (t *installSourceTool) tryGitHubRepo(ctx context.Context, req request) ([]action, []string) {
+	if req.Kind != "auto" && req.Kind != "skill" && req.Kind != "mcp" {
+		return nil, nil
+	}
+	src, ok := parseGitHubRepoSource(req.Source)
+	if !ok {
+		return nil, nil
+	}
+	var warnings []string
+	for _, branch := range src.branches() {
+		if req.Kind == "auto" || req.Kind == "mcp" {
+			cand := fmt.Sprintf("https://raw.githubusercontent.com/%s/%s/%s/%s", src.Owner, src.Repo, branch, joinURLPath(src.Path, ".mcp.json"))
+			actions, _, err := t.planDownloadedURL(ctx, req, cand)
+			if err == nil && len(actions) > 0 {
+				return actions, warnings
+			}
+			if err != nil {
+				warnings = append(warnings, fmt.Sprintf("%s: %s", cand, err.Error()))
+			}
+		}
+		if req.Kind == "auto" || req.Kind == "skill" {
+			actions, skillWarnings, err := t.planGitHubSkillRepo(ctx, req, src, branch)
+			warnings = append(warnings, skillWarnings...)
+			if err == nil && len(actions) > 0 {
+				return actions, warnings
+			}
+			if err != nil {
+				warnings = append(warnings, fmt.Sprintf("github repo %s/%s@%s: %s", src.Owner, src.Repo, branch, err.Error()))
+			}
+		}
+	}
+	return nil, warnings
+}
+
+type githubRepoSource struct {
+	Owner  string
+	Repo   string
+	Branch string
+	Path   string
+}
+
+func (s githubRepoSource) branches() []string {
+	if s.Branch != "" {
+		return []string{s.Branch}
+	}
+	return []string{"main", "master"}
+}
+
+func parseGitHubRepoSource(source string) (githubRepoSource, bool) {
+	u, err := url.Parse(source)
+	if err != nil || !strings.EqualFold(u.Hostname(), "github.com") {
+		return githubRepoSource{}, false
+	}
+	parts := strings.Split(strings.Trim(u.Path, "/"), "/")
+	if len(parts) < 2 {
+		return githubRepoSource{}, false
+	}
+	out := githubRepoSource{Owner: parts[0], Repo: strings.TrimSuffix(parts[1], ".git")}
+	if len(parts) >= 4 && parts[2] == "tree" {
+		out.Branch = parts[3]
+		if len(parts) > 4 {
+			out.Path = strings.Join(parts[4:], "/")
+		}
+	}
+	return out, true
+}
+
+type githubContentEntry struct {
+	Name        string `json:"name"`
+	Path        string `json:"path"`
+	Type        string `json:"type"`
+	DownloadURL string `json:"download_url"`
+}
+
+func (t *installSourceTool) planGitHubSkillRepo(ctx context.Context, req request, src githubRepoSource, branch string) ([]action, []string, error) {
+	cands, warnings, err := t.scanGitHubSkills(ctx, req, src, branch)
+	if err != nil {
+		return nil, warnings, err
+	}
+	if len(cands) == 0 {
+		return nil, warnings, newErr(ErrManifestMissing, "no SKILL.md or <name>.md skills found under GitHub repo path %s", firstNonEmpty(src.Path, "."))
+	}
+	actions := make([]action, 0, len(cands))
+	for _, cand := range cands {
+		actions = append(actions, t.skillAction(req, cand, "copy"))
+	}
+	sort.Slice(actions, func(i, j int) bool { return actions[i].Name < actions[j].Name })
+	return actions, warnings, nil
+}
+
+func (t *installSourceTool) scanGitHubSkills(ctx context.Context, req request, src githubRepoSource, branch string) ([]skillCandidate, []string, error) {
+	var out []skillCandidate
+	var warnings []string
+	var walk func(path string, depth int) error
+	walk = func(path string, depth int) error {
+		if depth > maxSkillScanDepth {
+			return nil
+		}
+		entries, err := t.fetchGitHubContents(ctx, src, branch, path)
+		if err != nil {
+			return err
+		}
+		sort.Slice(entries, func(i, j int) bool { return entries[i].Path < entries[j].Path })
+		for _, entry := range entries {
+			if len(out) >= maxSkillScanCount {
+				return newErr(ErrInvalidManifest, "too many skills under GitHub repo; limit is %d", maxSkillScanCount)
+			}
+			switch entry.Type {
+			case "dir":
+				if skipSkillRepoDir(entry.Name) {
+					continue
+				}
+				if err := walk(entry.Path, depth+1); err != nil {
+					return err
+				}
+			case "file":
+				cand, ok, warning := t.githubSkillCandidate(ctx, req, entry, src.Repo)
+				if warning != "" {
+					warnings = append(warnings, warning)
+				}
+				if ok {
+					out = append(out, cand)
+				}
+			}
+		}
+		return nil
+	}
+	err := walk(src.Path, 0)
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, warnings, err
+}
+
+func (t *installSourceTool) githubSkillCandidate(ctx context.Context, req request, entry githubContentEntry, repoName string) (skillCandidate, bool, string) {
+	if entry.DownloadURL == "" {
+		return skillCandidate{}, false, ""
+	}
+	base := filepath.Base(entry.Path)
+	if !strings.EqualFold(filepath.Ext(base), ".md") {
+		return skillCandidate{}, false, ""
+	}
+	fallback := strings.TrimSuffix(base, filepath.Ext(base))
+	if strings.EqualFold(base, skill.SkillFile) {
+		parent := filepath.Base(filepath.Dir(entry.Path))
+		if parent == "." || parent == "" {
+			parent = repoName
+		}
+		fallback = parent
+	}
+	body, err := t.fetchText(ctx, entry.DownloadURL)
+	if err != nil {
+		return skillCandidate{}, false, fmt.Sprintf("%s: %s", entry.DownloadURL, err.Error())
+	}
+	cand, err := parseSkillContent(body, fallback, entry.DownloadURL, req.strict())
+	if err != nil {
+		if strings.EqualFold(base, skill.SkillFile) {
+			return skillCandidate{}, false, err.Error()
+		}
+		return skillCandidate{}, false, ""
+	}
+	cand.SourcePath = entry.DownloadURL
+	cand.Content = body
+	return cand, true, ""
+}
+
+func (t *installSourceTool) fetchGitHubContents(ctx context.Context, src githubRepoSource, branch, path string) ([]githubContentEntry, error) {
+	apiURL, err := url.Parse(strings.TrimRight(githubAPIBaseURL, "/"))
+	if err != nil {
+		return nil, err
+	}
+	apiURL.Path = "/" + joinURLPath(apiURL.Path, "repos", src.Owner, src.Repo, "contents", path)
+	q := apiURL.Query()
+	q.Set("ref", branch)
+	apiURL.RawQuery = q.Encode()
+	body, err := t.fetchText(ctx, apiURL.String())
+	if err != nil {
+		return nil, err
+	}
+	var entries []githubContentEntry
+	if err := json.Unmarshal([]byte(body), &entries); err == nil {
+		return entries, nil
+	}
+	var single githubContentEntry
+	if err := json.Unmarshal([]byte(body), &single); err != nil {
+		return nil, newErr(ErrInvalidManifest, "%s: invalid GitHub contents response: %v", apiURL.String(), err)
+	}
+	return []githubContentEntry{single}, nil
+}
+
+func skipSkillRepoDir(name string) bool {
+	switch strings.ToLower(strings.TrimSpace(name)) {
+	case "", ".git", ".github", "node_modules", "references", "scripts", "assets":
+		return true
+	default:
+		return false
+	}
+}
+
+func joinURLPath(parts ...string) string {
+	var cleaned []string
+	for _, part := range parts {
+		part = strings.Trim(part, "/")
+		if part != "" {
+			cleaned = append(cleaned, part)
+		}
+	}
+	return strings.Join(cleaned, "/")
+}
+
+func (t *installSourceTool) planLocal(req request, path string, info os.FileInfo) ([]action, []string, error) {
+	var actions []action
+	var warnings []string
+	if req.Kind == "auto" || req.Kind == "mcp" {
+		mcpPath := path
+		if info.IsDir() {
+			mcpPath = filepath.Join(path, ".mcp.json")
+		}
+		if filepath.Base(mcpPath) == ".mcp.json" {
+			entries, mcpWarnings, err := readMCPJSON(mcpPath)
+			if err == nil && len(entries) > 0 {
+				for _, e := range entries {
+					actions = append(actions, t.mcpEntryAction(req, e, mcpPath))
+				}
+				warnings = append(warnings, mcpWarnings...)
+			} else if req.Kind == "mcp" {
+				return nil, nil, err
+			}
+		}
+		if !info.IsDir() && isExecutable(path, info) && filepath.Base(path) != ".mcp.json" {
+			actions = append(actions, t.localExecutableMCPAction(req, path))
+		}
+	}
+	if req.Kind == "auto" || req.Kind == "skill" {
+		skillActions, err := t.localSkillActions(req, path, info)
+		if err != nil && req.Kind == "skill" {
+			return nil, nil, err
+		}
+		if err != nil && req.Kind == "auto" {
+			warnings = append(warnings, err.Error())
+		}
+		actions = append(actions, skillActions...)
+	}
+	if len(actions) == 0 {
+		return nil, warnings, newErr(ErrManifestMissing, "no installable MCP server or skill found at %s", path)
+	}
+	sort.SliceStable(actions, func(i, j int) bool {
+		if actions[i].Kind != actions[j].Kind {
+			return actions[i].Kind < actions[j].Kind
+		}
+		return actions[i].Name < actions[j].Name
+	})
+	return actions, warnings, nil
+}
+
+func (t *installSourceTool) localSkillActions(req request, path string, info os.FileInfo) ([]action, error) {
+	strict := req.strict()
+	if !info.IsDir() {
+		if !strings.EqualFold(filepath.Ext(path), ".md") {
+			return nil, newErr(ErrUnsupportedKind, "not a markdown skill file: %s", path)
+		}
+		fallback := strings.TrimSuffix(filepath.Base(path), filepath.Ext(path))
+		if strings.EqualFold(filepath.Base(path), skill.SkillFile) {
+			fallback = filepath.Base(filepath.Dir(path))
+		}
+		cand, err := readSkillFile(path, fallback, strict)
+		if err != nil {
+			return nil, err
+		}
+		if strings.EqualFold(filepath.Base(path), skill.SkillFile) {
+			cand.IsDir = true
+			cand.SourcePath = filepath.Dir(path)
+			cand.RootPath = filepath.Dir(filepath.Dir(path))
+		} else {
+			cand.RootPath = filepath.Dir(path)
+		}
+		if req.Name != "" {
+			cand.Name = req.Name
+		}
+		if req.Mode == "register" {
+			root := cand.RootPath
+			if root == "" {
+				root = filepath.Dir(path)
+			}
+			return []action{t.skillRootAction(req, root, []string{cand.Name})}, nil
+		}
+		return []action{t.skillAction(req, cand, modeForSingleSkill(req.Mode))}, nil
+	}
+	if st, err := os.Stat(filepath.Join(path, skill.SkillFile)); err == nil && st.Mode().IsRegular() {
+		cand, err := readSkillFile(filepath.Join(path, skill.SkillFile), filepath.Base(path), strict)
+		if err != nil {
+			return nil, err
+		}
+		cand.IsDir = true
+		cand.SourcePath = path
+		cand.RootPath = filepath.Dir(path)
+		if req.Name != "" {
+			cand.Name = req.Name
+		}
+		if req.Mode == "register" {
+			return []action{t.skillRootAction(req, filepath.Dir(path), []string{cand.Name})}, nil
+		}
+		return []action{t.skillAction(req, cand, modeForSingleSkill(req.Mode))}, nil
+	}
+	cands, err := scanSkillRoot(path, strict)
+	if err != nil {
+		return nil, err
+	}
+	if len(cands) == 0 {
+		return nil, newErr(ErrManifestMissing, "no SKILL.md or <name>.md skills found under %s", path)
+	}
+	mode := req.Mode
+	if mode == "auto" {
+		mode = "register"
+	}
+	if mode == "register" {
+		byRoot := map[string][]string{}
+		for _, cand := range cands {
+			root := cand.RootPath
+			if root == "" {
+				root = path
+			}
+			byRoot[root] = append(byRoot[root], cand.Name)
+		}
+		roots := make([]string, 0, len(byRoot))
+		for root := range byRoot {
+			roots = append(roots, root)
+		}
+		sort.Strings(roots)
+		actions := make([]action, 0, len(roots))
+		for _, root := range roots {
+			rootNames := byRoot[root]
+			sort.Strings(rootNames)
+			actions = append(actions, t.skillRootAction(req, root, rootNames))
+		}
+		return actions, nil
+	}
+	actions := make([]action, 0, len(cands))
+	for _, cand := range cands {
+		actions = append(actions, t.skillAction(req, cand, mode))
+	}
+	return actions, nil
+}
+
+// strict returns the effective strict setting, defaulting to true when the
+// caller did not set the field.
+func (r request) strict() bool {
+	if r.Strict == nil {
+		return true
+	}
+	return *r.Strict
+}
diff --git a/internal/installsource/skill.go b/internal/installsource/skill.go
new file mode 100644
index 000000000..446679331
--- /dev/null
+++ b/internal/installsource/skill.go
@@ -0,0 +1,355 @@
+package installsource
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"reasonix/internal/config"
+	"reasonix/internal/frontmatter"
+	"reasonix/internal/skill"
+)
+
+const (
+	maxSkillScanDepth = 3
+	maxSkillScanCount = 200
+	maxSkillCopyBytes = 20 << 20
+)
+
+// skillAction builds the DTO for a single-skill install (copy or link).
+func (t *installSourceTool) skillAction(req request, cand skillCandidate, mode string) action {
+	actionName := "copy_skill"
+	if mode == "link" {
+		actionName = "link_skill"
+	}
+	canonical, _ := t.skillCanonicalPath(cand.Name, req.Scope)
+	root, _ := t.skillInstallRoot(req.Scope)
+	a := action{
+		Kind:          "skill",
+		Action:        actionName,
+		Name:          cand.Name,
+		Source:        cand.SourcePath,
+		Target:        canonical,
+		Scope:         req.Scope,
+		Mode:          mode,
+		ConfigPath:    t.skillConfigPath(req.Scope),
+		Skills:        []string{cand.Name},
+		SkillCount:    1,
+		Layout:        "canonical_dir",
+		InstallRoot:   root,
+		CanonicalPath: canonical,
+		skill:         cand,
+	}
+	a.RiskLevel, a.RiskReasons = skillActionRisk(mode, cand)
+	if mode == "link" && !isLinkTargetSafe(cand.SourcePath, t.home, t.root) {
+		a.RiskLevel = RiskHigh
+		a.RiskReasons = append(a.RiskReasons, "link target is an absolute path outside the project or home root")
+	}
+	return a
+}
+
+// skillActionRisk explains the risk budget for a skill install. The model
+// uses this to decide whether to call apply=true directly or to ask first.
+func skillActionRisk(mode string, cand skillCandidate) (RiskLevel, []string) {
+	reasons := []string{}
+	level := RiskLow
+	if mode == "link" {
+		// Link installs a pointer into a foreign tree; an untrusted source
+		// could expose anything at runtime, so we always classify as medium
+		// at minimum.
+		level = RiskMedium
+		reasons = append(reasons, "symlink to a foreign path")
+	}
+	if cand.IsDir && mode == "copy" {
+		if level == RiskLow {
+			level = RiskMedium
+		}
+		reasons = append(reasons, "copy of a directory")
+	}
+	return level, reasons
+}
+
+// skillRootAction builds the DTO for registering a whole skill directory.
+func (t *installSourceTool) skillRootAction(req request, path string, names []string) action {
+	return action{
+		Kind:        "skill",
+		Action:      "register_skill_root",
+		Name:        "",
+		Source:      path,
+		Target:      path,
+		ConfigPath:  t.skillConfigPath(req.Scope),
+		Scope:       req.Scope,
+		Mode:        "register",
+		Skills:      names,
+		SkillCount:  len(names),
+		Layout:      "registered_root",
+		InstallRoot: path,
+		RiskLevel:   RiskMedium,
+		RiskReasons: []string{"adds a new skill root to the active config"},
+	}
+}
+
+func (t *installSourceTool) skillInstallRoot(scope string) (string, error) {
+	if scope == "global" {
+		if t.home == "" {
+			return "", newErr(ErrSourceUnreadable, "global skill install requires a home directory")
+		}
+		return filepath.Join(t.home, ".reasonix", skill.SkillsDirname), nil
+	}
+	return filepath.Join(t.root, ".reasonix", skill.SkillsDirname), nil
+}
+
+// skillCanonicalPath computes the canonical install destination:
+// <scope>/skills/<skill-name>/SKILL.md. Flat <name>.md remains readable for
+// backward compatibility, but the installer no longer writes it by default.
+func (t *installSourceTool) skillCanonicalPath(name, scope string) (string, error) {
+	if !config.IsValidSkillName(name) {
+		return "", newErr(ErrInvalidManifest, "invalid skill name %q", name)
+	}
+	root, err := t.skillInstallRoot(scope)
+	if err != nil {
+		return "", err
+	}
+	return filepath.Join(root, name, skill.SkillFile), nil
+}
+
+// verifySkill confirms the installed skill is reachable through a freshly
+// built Store. It is the post-install guard against partial failures.
+func (t *installSourceTool) verifySkill(scope, name string, act *action) error {
+	custom := []string(nil)
+	if scope == "global" {
+		cfg, err := t.loadConfig()
+		if err != nil {
+			return err
+		}
+		custom = cfg.SkillCustomPaths()
+	}
+	var stderr bytes.Buffer
+	store := skill.New(skill.Options{HomeDir: t.home, ProjectRoot: t.root, CustomPaths: custom, DisableBuiltins: true, Stderr: &stderr})
+	sk, ok := store.Read(name)
+	if !ok {
+		return newErr(ErrSourceUnreadable, "skill %q is installed but not discoverable", name)
+	}
+	act.Discoverable = true
+	act.CanonicalPath = sk.Path
+	for _, listed := range store.List() {
+		if listed.Name == name {
+			act.Indexed = true
+			break
+		}
+	}
+	if strings.TrimSpace(sk.Description) == "" {
+		act.Warnings = append(act.Warnings, fmt.Sprintf("skill %q has no description frontmatter; it is installed but the skills index will use a placeholder", name))
+	}
+	if msg := strings.TrimSpace(stderr.String()); msg != "" {
+		act.Warnings = append(act.Warnings, msg)
+	}
+	return nil
+}
+
+// skillConflictTargets returns every existing layout that would collide with
+// installing name: the canonical directory, its SKILL.md, and the legacy flat
+// file. The apply step checks all of them so new canonical installs don't
+// silently shadow older <name>.md installs.
+func (t *installSourceTool) skillConflictTargets(name, scope string) ([]string, error) {
+	canonical, err := t.skillCanonicalPath(name, scope)
+	if err != nil {
+		return nil, err
+	}
+	dir := filepath.Dir(canonical)
+	return []string{dir, canonical, filepath.Join(filepath.Dir(dir), name+".md")}, nil
+}
+
+// readSkillFile reads and validates a single skill file. The fallback name
+// is used when the frontmatter does not declare one.
+func readSkillFile(path, fallbackName string, strict bool) (skillCandidate, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return skillCandidate{}, err
+	}
+	cand, err := parseSkillContent(string(b), fallbackName, path, strict)
+	if err != nil {
+		return skillCandidate{}, err
+	}
+	cand.SourcePath = path
+	return cand, nil
+}
+
+// parseSkillContent validates the YAML frontmatter of a skill file. With
+// strict=true (the default) we require a `name` and a `description`; with
+// strict=false a missing description is allowed and the body may be empty —
+// useful for installing raw files the user already trusts.
+func parseSkillContent(content, fallbackName, source string, strict bool) (skillCandidate, error) {
+	bom := "\uFEFF"
+	content = strings.TrimPrefix(strings.ReplaceAll(content, "\r\n", "\n"), bom)
+	fm, body := frontmatter.Split(content)
+	name := strings.TrimSpace(fallbackName)
+	if v := strings.TrimSpace(fm["name"]); v != "" {
+		name = v
+	}
+	if !config.IsValidSkillName(name) {
+		return skillCandidate{}, newErr(ErrInvalidManifest, "skill %q at %s has an invalid name", name, source)
+	}
+	desc := collapseSpaces(fm["description"])
+	if strict {
+		if desc == "" {
+			return skillCandidate{}, newErr(ErrInvalidManifest, "skill %q at %s is missing description frontmatter", name, source)
+		}
+		if strings.TrimSpace(body) == "" {
+			return skillCandidate{}, newErr(ErrInvalidManifest, "skill %q at %s has an empty body", name, source)
+		}
+	}
+	return skillCandidate{Name: name, Description: desc, SourcePath: source, Content: content}, nil
+}
+
+// scanSkillRoot enumerates skills under a directory with bounded recursion:
+// any <name>/SKILL.md is a directory-layout skill, and any <name>.md is a
+// flat compatibility skill. RootPath records the containing directory that must
+// be registered for the runtime Store to discover that candidate.
+func scanSkillRoot(root string, strict bool) ([]skillCandidate, error) {
+	var out []skillCandidate
+	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if path == root {
+			return nil
+		}
+		rel, err := filepath.Rel(root, path)
+		if err != nil {
+			return err
+		}
+		depth := pathDepth(rel)
+		if d.IsDir() {
+			if depth > maxSkillScanDepth {
+				return filepath.SkipDir
+			}
+			if strings.EqualFold(d.Name(), ".git") {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		if len(out) >= maxSkillScanCount {
+			return newErr(ErrInvalidManifest, "too many skills under %s; limit is %d", root, maxSkillScanCount)
+		}
+		if !d.Type().IsRegular() || !strings.EqualFold(filepath.Ext(d.Name()), ".md") {
+			return nil
+		}
+		parent := filepath.Dir(path)
+		if strings.EqualFold(d.Name(), skill.SkillFile) {
+			containerDepth := pathDepth(mustRel(root, parent))
+			if containerDepth > maxSkillScanDepth {
+				return nil
+			}
+			if parent == root {
+				return nil
+			}
+			cand, err := readSkillFile(path, filepath.Base(parent), strict)
+			if err == nil {
+				cand.IsDir = true
+				cand.SourcePath = parent
+				cand.RootPath = filepath.Dir(parent)
+				out = append(out, cand)
+			}
+			return nil
+		}
+		containerDepth := pathDepth(mustRel(root, parent))
+		if containerDepth > maxSkillScanDepth {
+			return nil
+		}
+		stem := strings.TrimSuffix(d.Name(), filepath.Ext(d.Name()))
+		cand, err := readSkillFile(path, stem, strict)
+		if err == nil {
+			cand.RootPath = parent
+			out = append(out, cand)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
+	return out, nil
+}
+
+func pathDepth(rel string) int {
+	if rel == "." || rel == "" {
+		return 0
+	}
+	return len(strings.Split(filepath.Clean(rel), string(filepath.Separator)))
+}
+
+func mustRel(base, path string) string {
+	rel, err := filepath.Rel(base, path)
+	if err != nil {
+		return "."
+	}
+	return rel
+}
+
+// copyDir walks src and writes a parallel tree under dst. O_EXCL refuses to
+// overwrite a leaf; a leftover partial tree is left on disk for the user to
+// inspect (we never rm -rf). Symlinks inside src are followed once and
+// copied as the resolved file, which is what skill directories expect.
+func copyDir(src, dst string) error {
+	var copied int64
+	return filepath.WalkDir(src, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		rel, err := filepath.Rel(src, path)
+		if err != nil {
+			return err
+		}
+		target := filepath.Join(dst, rel)
+		if d.IsDir() {
+			if strings.EqualFold(d.Name(), ".git") {
+				return filepath.SkipDir
+			}
+			return os.MkdirAll(target, 0o755)
+		}
+		if !d.Type().IsRegular() {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		copied += info.Size()
+		if copied > maxSkillCopyBytes {
+			return newErr(ErrInvalidManifest, "skill directory exceeds %d bytes", maxSkillCopyBytes)
+		}
+		in, err := os.Open(path)
+		if err != nil {
+			return err
+		}
+		defer in.Close()
+		if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {
+			return err
+		}
+		out, err := os.OpenFile(target, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+		if err != nil {
+			return err
+		}
+		defer out.Close()
+		_, err = io.Copy(out, in)
+		return err
+	})
+}
+
+func writeNewFile(path string, content []byte) error {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+	if _, err := f.Write(content); err != nil {
+		return err
+	}
+	return nil
+}
diff --git a/internal/installsource/types.go b/internal/installsource/types.go
new file mode 100644
index 000000000..ef618097c
--- /dev/null
+++ b/internal/installsource/types.go
@@ -0,0 +1,151 @@
+package installsource
+
+import (
+	"encoding/json"
+
+	"reasonix/internal/config"
+)
+
+// request mirrors the public schema. Fields stay exported because Execute
+// unmarshals directly into this struct; the struct comment is the source of
+// truth for the field semantics surfaced to the model.
+type request struct {
+	Op        string            `json:"op"`        // "install" (default) | "uninstall"
+	Source    string            `json:"source"`    // required for install; ignored for uninstall
+	Kind      string            `json:"kind"`      // auto|skill|mcp (install only)
+	Apply     bool              `json:"apply"`     // install only: actually write/connect
+	Scope     string            `json:"scope"`     // project|global
+	Mode      string            `json:"mode"`      // auto|copy|link|register (skill install)
+	Name      string            `json:"name"`      // override the discovered name
+	Transport string            `json:"transport"` // auto|stdio|http|sse
+	Command   string            `json:"command"`
+	Args      []string          `json:"args"`
+	Env       map[string]string `json:"env"`
+	Headers   map[string]string `json:"headers"`
+	Tier      string            `json:"tier"`
+	Replace   bool              `json:"replace"` // overwrite existing entries
+	Strict    *bool             `json:"strict"`  // nil -> true; require skill frontmatter
+	// PlanID is echoed back on a confirm-apply call so the host can refuse
+	// to apply a plan that does not match the one it approved.
+	PlanID string `json:"planId"`
+}
+
+// response is the JSON shape returned to the model. Status is one of
+// "planned" (apply=false, no writes), "done" (all actions succeeded),
+// "partial" (some actions succeeded), "failed" (no actions succeeded), or
+// "blocked" (no plan could be produced). The `Kind` field is preserved for
+// back-compat with callers that only handle a single capability; `Kinds`
+// reports per-kind counts.
+type response struct {
+	OK       bool      `json:"ok"`
+	Status   string    `json:"status"`
+	Op       string    `json:"op"`
+	Applied  bool      `json:"applied"`
+	Source   string    `json:"source"`
+	Name     string    `json:"name,omitempty"`
+	Kind     string    `json:"kind"`            // legacy single kind, "" when no plan
+	Kinds    kindTally `json:"kinds,omitempty"` // counts per kind
+	Scope    string    `json:"scope"`
+	Mode     string    `json:"mode"`
+	PlanID   string    `json:"planId,omitempty"`
+	Actions  []action  `json:"actions"`
+	Warnings []string  `json:"warnings,omitempty"`
+	Next     string    `json:"next,omitempty"`
+}
+
+// kindTally reports per-kind counts. It is a struct (not a map) so the JSON
+// shape stays stable: missing fields read as zero, and we can add new kinds
+// without breaking old clients.
+type kindTally struct {
+	Skill int `json:"skill"`
+	MCP   int `json:"mcp"`
+}
+
+// action is the per-install-step DTO. The Kind/Action pair drives the apply
+// dispatcher; RiskLevel/RiskReasons help the calling skill decide whether to
+// ask the user before apply=true.
+type action struct {
+	Kind          string            `json:"kind"`      // "skill" | "mcp"
+	Action        string            `json:"action"`    // copy_skill|link_skill|register_skill_root|install_mcp_server|remove_skill|remove_skill_root|remove_mcp_server
+	Status        string            `json:"status"`    // planned|done|failed
+	RiskLevel     RiskLevel         `json:"riskLevel"` // low|medium|high
+	RiskReasons   []string          `json:"riskReasons,omitempty"`
+	Name          string            `json:"name,omitempty"`
+	Source        string            `json:"source,omitempty"`
+	Target        string            `json:"target,omitempty"`
+	ConfigPath    string            `json:"configPath,omitempty"`
+	Scope         string            `json:"scope,omitempty"`
+	Mode          string            `json:"mode,omitempty"`
+	Transport     string            `json:"transport,omitempty"`
+	URL           string            `json:"url,omitempty"`
+	Command       string            `json:"command,omitempty"`
+	Args          []string          `json:"args,omitempty"`
+	Env           map[string]string `json:"env,omitempty"`
+	Headers       map[string]string `json:"headers,omitempty"`
+	Skills        []string          `json:"skills,omitempty"`
+	SkillCount    int               `json:"skillCount,omitempty"`
+	Layout        string            `json:"layout,omitempty"`        // canonical_dir|flat_compat|registered_root
+	InstallRoot   string            `json:"installRoot,omitempty"`   // skills root or registered custom root
+	CanonicalPath string            `json:"canonicalPath,omitempty"` // <skill-name>/SKILL.md when applicable
+	Discoverable  bool              `json:"discoverable,omitempty"`  // Store.Read can load it after apply/register
+	Indexed       bool              `json:"indexed,omitempty"`       // Store.List includes it for the skills index
+	ToolCount     int               `json:"toolCount,omitempty"`
+	Warnings      []string          `json:"warnings,omitempty"`
+	Error         string            `json:"error,omitempty"`
+	Next          string            `json:"next,omitempty"`
+
+	// Internal state used by apply. Stripped by publicActions before
+	// serializing to JSON.
+	entry      config.PluginEntry
+	skill      skillCandidate
+	disconnect func() // optional MCP rollback; nil when not connected
+}
+
+func actionPlanKey(a action) string {
+	return a.Kind + ":" + a.Name + ":" + a.Action + ":" + a.Source + ":" + a.Target + ":" + a.ConfigPath
+}
+
+// skillCandidate is a parsed skill file/directory ready to install. The
+// caller decides whether to copy, link, or register the source path.
+type skillCandidate struct {
+	Name        string
+	Description string
+	SourcePath  string
+	RootPath    string
+	IsDir       bool
+	Content     string
+}
+
+// summarizeKind returns a one-word kind label for callers that only want the
+// dominant capability. "mixed" is returned when the plan contains both
+// skills and MCP servers; counts live in response.Kinds.
+func summarizeKind(actions []action) string {
+	seen := map[string]bool{}
+	for _, a := range actions {
+		seen[a.Kind] = true
+	}
+	if len(seen) > 1 {
+		return "mixed"
+	}
+	for k := range seen {
+		return k
+	}
+	return ""
+}
+
+// publicActions strips unexported state from each action so the JSON
+// response does not leak internal config types.
+func publicActions(in []action) []action {
+	out := make([]action, len(in))
+	for i := range in {
+		out[i] = in[i]
+		out[i].entry = config.PluginEntry{}
+		out[i].skill = skillCandidate{}
+	}
+	return out
+}
+
+func marshalJSON(v any) string {
+	b, _ := json.Marshal(v)
+	return string(b)
+}
diff --git a/internal/plugin/transport_stdio.go b/internal/plugin/transport_stdio.go
index 74f56fd8b..e14e762b4 100644
--- a/internal/plugin/transport_stdio.go
+++ b/internal/plugin/transport_stdio.go
@@ -112,6 +112,17 @@ func resolveStdioExecutable(ctx context.Context, s Spec, env []string) (string,
 			currentPath = fallbackPath
 		}
 	}
+	if runtime.GOOS == "windows" {
+		fallbackPath := mergePathLists(windowsStdioFallbackPATH(env), currentPath)
+		if fallbackPath != currentPath {
+			fallbackEnv := setEnvValue(env, "PATH", fallbackPath)
+			if exe, ok := lookPathInEnv(s.Command, fallbackEnv); ok {
+				return exe, fallbackEnv, nil
+			}
+			env = fallbackEnv
+			currentPath = fallbackPath
+		}
+	}
 
 	return "", env, fmt.Errorf("stdio plugin %q: command %q not found on PATH; GUI launches and non-interactive sessions may not inherit your shell PATH. Use an absolute command path or set PATH in the MCP server env. PATH=%q",
 		s.Name, s.Command, currentPath)
@@ -176,6 +187,53 @@ func isExecutableFile(path string) bool {
 	return info.Mode().Perm()&0o111 != 0
 }
 
+func windowsStdioFallbackPATH(env []string) string {
+	if runtime.GOOS != "windows" {
+		return ""
+	}
+	programFiles, _ := envValue(env, "ProgramFiles")
+	programFilesX86, _ := envValue(env, "ProgramFiles(x86)")
+	localAppData, _ := envValue(env, "LOCALAPPDATA")
+	appData, _ := envValue(env, "APPDATA")
+	userProfile, _ := envValue(env, "USERPROFILE")
+	chocolatey, _ := envValue(env, "ChocolateyInstall")
+	if localAppData == "" && userProfile != "" {
+		localAppData = filepath.Join(userProfile, "AppData", "Local")
+	}
+	if appData == "" && userProfile != "" {
+		appData = filepath.Join(userProfile, "AppData", "Roaming")
+	}
+	candidates := []string{
+		filepath.Join(programFiles, "nodejs"),
+		filepath.Join(programFilesX86, "nodejs"),
+		filepath.Join(localAppData, "Programs", "nodejs"),
+		filepath.Join(appData, "npm"),
+		filepath.Join(localAppData, "Microsoft", "WindowsApps"),
+		filepath.Join(userProfile, "scoop", "shims"),
+		filepath.Join(userProfile, ".bun", "bin"),
+		filepath.Join(userProfile, ".cargo", "bin"),
+		filepath.Join(chocolatey, "bin"),
+	}
+	var existing []string
+	for _, dir := range candidates {
+		if isDir(dir) {
+			existing = append(existing, dir)
+		}
+	}
+	return strings.Join(existing, string(os.PathListSeparator))
+}
+
+func isDir(path string) bool {
+	if path == "" {
+		return false
+	}
+	if !filepath.IsAbs(path) {
+		return false
+	}
+	info, err := os.Stat(path)
+	return err == nil && info.IsDir()
+}
+
 func defaultStdioShellPATH(ctx context.Context) string {
 	if runtime.GOOS == "windows" {
 		return ""
diff --git a/internal/plugin/transport_stdio_windows_test.go b/internal/plugin/transport_stdio_windows_test.go
index 4c56722ca..9c167fd63 100644
--- a/internal/plugin/transport_stdio_windows_test.go
+++ b/internal/plugin/transport_stdio_windows_test.go
@@ -32,6 +32,34 @@ func TestResolveStdioExecutableWindowsPathAndPATHEXT(t *testing.T) {
 	}
 }
 
+func TestResolveStdioExecutableWindowsUsesCommonNodeFallback(t *testing.T) {
+	root := t.TempDir()
+	localAppData := filepath.Join(root, "Local")
+	nodeDir := filepath.Join(localAppData, "Programs", "nodejs")
+	if err := os.MkdirAll(nodeDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	npx := filepath.Join(nodeDir, "npx.cmd")
+	if err := os.WriteFile(npx, []byte("@echo off\r\n"), 0o644); err != nil {
+		t.Fatalf("write fake npx.cmd: %v", err)
+	}
+
+	exe, env, err := resolveStdioExecutable(context.Background(), Spec{Name: "fs", Command: "npx"}, []string{
+		"Path=",
+		"PATHEXT=.CMD;.EXE",
+		"LOCALAPPDATA=" + localAppData,
+	})
+	if err != nil {
+		t.Fatalf("resolveStdioExecutable: %v", err)
+	}
+	if !strings.EqualFold(exe, npx) {
+		t.Fatalf("resolved executable = %q, want %q", exe, npx)
+	}
+	if got, ok := envValue(env, "PATH"); !ok || !strings.Contains(strings.ToLower(got), strings.ToLower(nodeDir)) {
+		t.Fatalf("env PATH = %q, %v; want node fallback dir", got, ok)
+	}
+}
+
 func TestSetEnvValueWindowsReplacesPathCaseInsensitively(t *testing.T) {
 	env := setEnvValue([]string{"Path=C:\\old", "OTHER=x"}, "PATH", "C:\\new")
 	if got, ok := envValue(env, "Path"); !ok || got != "C:\\new" {
diff --git a/internal/serve/wire.go b/internal/serve/wire.go
index a7b35f77a..07462cb6f 100644
--- a/internal/serve/wire.go
+++ b/internal/serve/wire.go
@@ -48,16 +48,22 @@ type wireAsk struct {
 	Questions []wireAskQuestion `json:"questions"`
 }
 
+type wireProfile struct {
+	Model  string `json:"model,omitempty"`
+	Effort string `json:"effort,omitempty"`
+}
+
 type wireTool struct {
-	ID        string `json:"id,omitempty"`
-	Name      string `json:"name"`
-	Args      string `json:"args,omitempty"`
-	Output    string `json:"output,omitempty"`
-	Err       string `json:"err,omitempty"`
-	ReadOnly  bool   `json:"readOnly"`
-	Truncated bool   `json:"truncated,omitempty"`
-	Partial   bool   `json:"partial,omitempty"`
-	ParentID  string `json:"parentId,omitempty"`
+	ID        string       `json:"id,omitempty"`
+	Name      string       `json:"name"`
+	Args      string       `json:"args,omitempty"`
+	Output    string       `json:"output,omitempty"`
+	Err       string       `json:"err,omitempty"`
+	ReadOnly  bool         `json:"readOnly"`
+	Truncated bool         `json:"truncated,omitempty"`
+	Partial   bool         `json:"partial,omitempty"`
+	ParentID  string       `json:"parentId,omitempty"`
+	Profile   *wireProfile `json:"profile,omitempty"`
 }
 
 type wireUsage struct {
@@ -140,12 +146,16 @@ func toWire(e event.Event) wireEvent {
 			w.Level = "info"
 		}
 	case event.ToolDispatch, event.ToolResult, event.ToolProgress:
-		w.Tool = &wireTool{
+		wt := &wireTool{
 			ID: e.Tool.ID, Name: e.Tool.Name, Args: e.Tool.Args,
 			Output: e.Tool.Output, Err: e.Tool.Err,
 			ReadOnly: e.Tool.ReadOnly, Truncated: e.Tool.Truncated,
 			Partial: e.Tool.Partial, ParentID: e.Tool.ParentID,
 		}
+		if e.Tool.Profile != nil {
+			wt.Profile = &wireProfile{Model: e.Tool.Profile.Model, Effort: e.Tool.Profile.Effort}
+		}
+		w.Tool = wt
 	case event.Usage:
 		if u := e.Usage; u != nil {
 			w.Usage = &wireUsage{
diff --git a/internal/serve/wire_test.go b/internal/serve/wire_test.go
index d9aab3ca7..722bd4c6f 100644
--- a/internal/serve/wire_test.go
+++ b/internal/serve/wire_test.go
@@ -16,6 +16,16 @@ func TestToWire(t *testing.T) {
 		}
 	})
 
+	t.Run("tool dispatch profile", func(t *testing.T) {
+		w := toWire(event.Event{Kind: event.ToolDispatch, Tool: event.Tool{
+			Name: "task", Args: `{"prompt":"x"}`,
+			Profile: &event.Profile{Model: "deepseek-pro", Effort: "max"},
+		}})
+		if w.Tool == nil || w.Tool.Profile == nil || w.Tool.Profile.Model != "deepseek-pro" || w.Tool.Profile.Effort != "max" {
+			t.Errorf("profile = %+v", w.Tool)
+		}
+	})
+
 	t.Run("usage with cost", func(t *testing.T) {
 		w := toWire(event.Event{
 			Kind:    event.Usage,
diff --git a/internal/skill/builtins.go b/internal/skill/builtins.go
index 644fd7a91..9a7937419 100644
--- a/internal/skill/builtins.go
+++ b/internal/skill/builtins.go
@@ -51,6 +51,35 @@ Your final answer:
 
 The 'task' the parent gave you is the research question. Stay on it.`
 
+const builtinInstallCapabilityBody = `This skill is INLINED. Use it when the user asks to install a Reasonix MCP server or skill from a URL, local file, local folder, .mcp.json, or package name. For removing a previously installed skill or MCP server, follow the "Uninstall" rules at the bottom — same tool, different op.
+
+Operate as an installer, not as a shell-script guesser:
+1. Extract the source string exactly from the user's request. It may be an https URL, GitHub URL, local path, .mcp.json, executable path, or npm package name.
+2. Decide kind only when it is explicit. Use kind="auto" when unsure.
+3. First call install_source with apply=false. Include scope when the user says project/global. Include mode when they say copy/link/register; otherwise leave mode="auto".
+4. Read the returned plan. If status is blocked or failed, report the concrete next step. Do not invent a command from a README when the tool could not identify a manifest.
+5. Inspect the plan's actions. Each one carries a riskLevel:
+   - low → safe to apply without asking.
+   - medium → safe to apply, but mention what was written.
+   - high → ask the user to confirm in one short question before apply=true. High actions include MCP installs that send auth headers, eager-tier servers, link targets that are absolute paths outside the project/home root, and any replace=true on an existing entry.
+6. If the plan is acceptable, call install_source again with apply=true and echo back the same planId you got from the planning call. The tool refuses to apply when the planId does not match, so always re-fetch by running apply=false again if the user changed their mind about the source.
+7. After apply=true, report what was installed, where it was persisted, and whether it is usable in the current session. For skills, prefer actions[].canonicalPath, actions[].installRoot, actions[].discoverable, and actions[].indexed over guessing from the source path. The plan's kinds field tells you how many skills vs MCP servers were touched.
+
+Defaults:
+- A folder containing many skills should be registered as a skill root, not copied.
+- A single SKILL.md, <name>.md, or <name>/SKILL.md should be copied unless the user asked to link/register. The installer writes canonical <skill-name>/SKILL.md paths by default; flat <name>.md is compatibility input, not the preferred output.
+- A local SKILL.md source may have references/, scripts/, assets/, or other sibling files. Treat its parent directory as the skill package so those files remain available after install.
+- Local skill folders may contain grouped skills up to a bounded depth. Let install_source decide which roots to register instead of telling the user to manually split every nested folder first.
+- Remote MCP URLs should use http unless the endpoint is explicitly SSE.
+- Package-name MCP installs should default to npx -y <package>.
+- Never put raw tokens in headers or config. Prefer ${VAR} placeholders and tell the user which env var to set.
+
+Uninstall (op=uninstall):
+- Use op=uninstall with the same name and scope as the original install. Source is ignored.
+- Skill and MCP server matching happen in the chosen scope's active config; if you don't know where the entry lives, ask the user. Removal is destructive but symmetric with a previously approved install, so it is applied directly (no approval step).
+
+Stop rather than guessing when the source is only a documentation page, README without a manifest, or a repo whose install command cannot be determined.`
+
 const builtinReviewBody = `You are running as a code-review subagent. Inspect the changes the user is about to ship — usually the current git branch vs its upstream — and produce a focused review the parent can hand back.
 
 How to operate:
@@ -180,6 +209,14 @@ func builtinSkills() []Skill {
 			RunAs:        RunSubagent,
 			AllowedTools: append(append([]string(nil), readCodeTools...), "web_fetch"),
 		},
+		{
+			Name:        "install-capability",
+			Description: "Install or uninstall Reasonix MCP servers and skills from a URL, GitHub/raw file, local path/folder, .mcp.json, executable, or package name. Plans with install_source (op=install or op=uninstall) before applying, surfacing per-action riskLevel.",
+			Body:        builtinInstallCapabilityBody,
+			Scope:       ScopeBuiltin,
+			Path:        "(builtin)",
+			RunAs:       RunInline,
+		},
 		{
 			Name:         "review",
 			Description:  "Review the pending changes (current branch diff by default) in an isolated subagent — flags correctness, security, missing tests, hidden behavior changes; reports a verdict + per-issue file:line. Read-only.",
diff --git a/internal/skill/skill.go b/internal/skill/skill.go
index 83c65033f..5a7b78526 100644
--- a/internal/skill/skill.go
+++ b/internal/skill/skill.go
@@ -62,6 +62,7 @@ type Skill struct {
 	AllowedTools []string
 	RunAs        RunAs  // inline | subagent
 	Model        string // optional model override for runAs=subagent (frontmatter `model:`)
+	Effort       string // optional effort for runAs=subagent (frontmatter `effort:`)
 }
 
 // IsValidName reports whether name is a usable skill identifier.
@@ -74,6 +75,7 @@ type Options struct {
 	ProjectRoot     string
 	CustomPaths     []string
 	DisabledNames   []string
+	MaxDepth        int
 	DisableBuiltins bool // suppress shipped built-ins (test-only knob)
 	// Stderr is the writer for diagnostic warnings. When nil, defaults to
 	// os.Stderr. Set to io.Discard to suppress output (e.g. during model
@@ -87,6 +89,7 @@ type Store struct {
 	projectRoot     string
 	customPaths     []string
 	disabled        map[string]bool
+	maxDepth        int
 	disableBuiltins bool
 	stderr          io.Writer
 }
@@ -122,6 +125,7 @@ func New(opts Options) *Store {
 		projectRoot:     root,
 		customPaths:     custom,
 		disabled:        disabledNameSet(opts.DisabledNames),
+		maxDepth:        normalizeMaxDepth(opts.MaxDepth),
 		disableBuiltins: opts.DisableBuiltins,
 		stderr:          stderr,
 	}
@@ -148,21 +152,14 @@ type Root struct {
 	Status   PathStatus
 }
 
-// roots returns the discovery directories, highest priority first: the
-// convention dirs (config.ConventionDirs: .reasonix / .agents / .agent / .claude)
-// under the project root → custom paths → the same convention dirs under the home
-// dir. A later root never overrides an earlier one.
+// roots returns the discovery directories, highest priority first: custom paths,
+// then the convention dirs under the home dir. Project roots are no longer scanned.
 func (s *Store) roots() []Root {
 	type de struct {
 		dir   string
 		scope Scope
 	}
 	var dirs []de
-	if s.projectRoot != "" {
-		for _, c := range config.ConventionDirs {
-			dirs = append(dirs, de{filepath.Join(s.projectRoot, c, SkillsDirname), ScopeProject})
-		}
-	}
 	for _, d := range s.customPaths {
 		dirs = append(dirs, de{d, ScopeCustom})
 	}
@@ -193,6 +190,23 @@ func (s *Store) disabledName(name string) bool {
 	return s.disabled[config.SkillNameKey(name)]
 }
 
+func normalizeMaxDepth(depth int) int {
+	const (
+		defaultDepth = 3
+		maxDepth     = 5
+	)
+	if depth == 0 {
+		return defaultDepth
+	}
+	if depth < 1 {
+		return 1
+	}
+	if depth > maxDepth {
+		return maxDepth
+	}
+	return depth
+}
+
 // pathStatus classifies a root directory without failing on the common case of
 // "not created yet".
 func pathStatus(dir string) PathStatus {
@@ -223,15 +237,7 @@ func (s *Store) List() []Skill {
 		if r.Status != StatusOK {
 			continue
 		}
-		entries, err := os.ReadDir(r.Dir)
-		if err != nil {
-			continue
-		}
-		for _, e := range entries {
-			sk, ok := s.readEntry(r.Dir, r.Scope, e)
-			if !ok {
-				continue
-			}
+		for _, sk := range s.discoverRoot(r) {
 			if s.disabledName(sk.Name) {
 				continue
 			}
@@ -267,24 +273,75 @@ func (s *Store) Read(name string) (Skill, bool) {
 	if s.disabledName(name) {
 		return Skill{}, false
 	}
-	for _, r := range s.roots() {
-		dirCand := filepath.Join(r.Dir, name, SkillFile)
-		if info, err := os.Stat(dirCand); err == nil && info.Mode().IsRegular() {
-			return s.parse(dirCand, name, r.Scope)
-		}
-		flatCand := filepath.Join(r.Dir, name+".md")
-		if info, err := os.Stat(flatCand); err == nil && info.Mode().IsRegular() {
-			return s.parse(flatCand, name, r.Scope)
+	for _, sk := range s.List() {
+		if sk.Name == name {
+			return sk, true
 		}
 	}
-	if !s.disableBuiltins {
-		for _, sk := range builtinSkills() {
-			if sk.Name == name {
-				return sk, true
+	return Skill{}, false
+}
+
+func (s *Store) discoverRoot(r Root) []Skill {
+	var out []Skill
+	s.scanDir(r.Dir, r.Scope, 1, map[string]bool{}, &out)
+	return out
+}
+
+func (s *Store) scanDir(dir string, scope Scope, depth int, seen map[string]bool, out *[]Skill) {
+	key := filepath.Clean(dir)
+	if resolved, err := filepath.EvalSymlinks(dir); err == nil {
+		key = filepath.Clean(resolved)
+	}
+	if seen[key] {
+		return
+	}
+	seen[key] = true
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	for _, e := range entries {
+		sk, ok := s.readEntry(dir, scope, e)
+		if ok {
+			if depth == 1 || strings.TrimSpace(sk.Description) != "" {
+				*out = append(*out, sk)
 			}
+			continue
 		}
+		if depth >= s.maxDepth || !s.canScanChildDir(dir, e) {
+			continue
+		}
+		s.scanDir(filepath.Join(dir, e.Name()), scope, depth+1, seen, out)
+	}
+}
+
+func (s *Store) canScanChildDir(dir string, e os.DirEntry) bool {
+	name := e.Name()
+	if shouldSkipScanDir(name) {
+		return false
+	}
+	full := filepath.Join(dir, name)
+	if e.IsDir() {
+		return true
+	}
+	if e.Type()&os.ModeSymlink == 0 {
+		return false
+	}
+	info, err := os.Stat(full)
+	return err == nil && info.IsDir()
+}
+
+func shouldSkipScanDir(name string) bool {
+	if strings.HasPrefix(name, ".") {
+		return true
+	}
+	switch strings.ToLower(name) {
+	case "assets", "node_modules", "references", "scripts":
+		return true
+	default:
+		return false
 	}
-	return Skill{}, false
 }
 
 // readEntry turns one directory entry into a skill. It resolves symlinks via
@@ -354,6 +411,7 @@ func (s *Store) parse(path, stem string, scope Scope) (Skill, bool) {
 		AllowedTools: parseAllowedTools(fm["allowed-tools"]),
 		RunAs:        parseRunAs(fm["runas"], fm["context"], fm["agent"]),
 		Model:        strings.TrimSpace(fm["model"]),
+		Effort:       strings.TrimSpace(fm["effort"]),
 	}, true
 }
 
@@ -362,9 +420,9 @@ func (s *Store) Create(name string, scope Scope) (string, error) {
 	return s.CreateWithContent(name, scope, stubBody(name))
 }
 
-// CreateWithContent writes caller-supplied file contents as a new flat
-// <name>.md skill, refusing to clobber an existing flat or directory-layout
-// skill of the same name. Returns the written path.
+// CreateWithContent writes caller-supplied file contents as a canonical
+// <name>/SKILL.md skill, refusing to clobber an existing directory-layout or
+// legacy flat skill of the same name. Returns the written path.
 func (s *Store) CreateWithContent(name string, scope Scope, content string) (string, error) {
 	if !IsValidName(name) {
 		return "", fmt.Errorf("invalid skill name %q — use letters, digits, '_', '-', '.'", name)
@@ -372,26 +430,26 @@ func (s *Store) CreateWithContent(name string, scope Scope, content string) (str
 	var root string
 	switch scope {
 	case ScopeProject:
-		if s.projectRoot == "" {
-			return "", fmt.Errorf("project scope requires a workspace — run from a project directory, or use global scope")
-		}
-		root = filepath.Join(s.projectRoot, ".reasonix", SkillsDirname)
+		return "", fmt.Errorf("project-scoped skills are no longer supported — skills are only written to ~/.reasonix/skills/; use scope='global'")
 	default:
 		root = filepath.Join(s.homeDir, ".reasonix", SkillsDirname)
 	}
 	flat := filepath.Join(root, name+".md")
 	folder := filepath.Join(root, name, SkillFile)
+	if _, err := os.Stat(flat); err == nil {
+		return "", fmt.Errorf("skill %q already exists at %s", name, flat)
+	}
 	if _, err := os.Stat(folder); err == nil {
 		return "", fmt.Errorf("skill %q already exists at %s", name, folder)
 	}
-	if err := os.MkdirAll(root, 0o755); err != nil {
+	if err := os.MkdirAll(filepath.Dir(folder), 0o755); err != nil {
 		return "", err
 	}
 	// O_EXCL so a concurrent create (or an existing file) is reported, not clobbered.
-	f, err := os.OpenFile(flat, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
+	f, err := os.OpenFile(folder, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o644)
 	if err != nil {
 		if os.IsExist(err) {
-			return "", fmt.Errorf("skill %q already exists at %s", name, flat)
+			return "", fmt.Errorf("skill %q already exists at %s", name, folder)
 		}
 		return "", err
 	}
@@ -399,7 +457,7 @@ func (s *Store) CreateWithContent(name string, scope Scope, content string) (str
 	if _, err := f.WriteString(content); err != nil {
 		return "", err
 	}
-	return flat, nil
+	return folder, nil
 }
 
 // loadBodyWithReferences appends a directory-layout skill's sibling
diff --git a/internal/skill/skill_test.go b/internal/skill/skill_test.go
index b58be70df..31b57fbce 100644
--- a/internal/skill/skill_test.go
+++ b/internal/skill/skill_test.go
@@ -29,22 +29,22 @@ func find(skills []Skill, name string) (Skill, bool) {
 	return Skill{}, false
 }
 
-func TestListPrecedenceProjectOverGlobal(t *testing.T) {
+func TestListPrecedenceCustomOverGlobal(t *testing.T) {
 	home := t.TempDir()
-	proj := t.TempDir()
-	writeSkill(t, proj, ".reasonix/skills/greet.md", "---\nname: greet\ndescription: project greet\n---\nproject body")
+	customDir := t.TempDir()
+	writeSkill(t, customDir, "greet.md", "---\nname: greet\ndescription: custom greet\n---\ncustom body")
 	writeSkill(t, home, ".reasonix/skills/greet.md", "---\ndescription: global greet\n---\nglobal body")
 	writeSkill(t, home, ".reasonix/skills/onlyglobal.md", "---\ndescription: only global\n---\nbody")
 
-	st := New(Options{HomeDir: home, ProjectRoot: proj, DisableBuiltins: true})
+	st := New(Options{HomeDir: home, CustomPaths: []string{customDir}, DisableBuiltins: true})
 	list := st.List()
 
 	greet, ok := find(list, "greet")
 	if !ok {
 		t.Fatal("greet not found")
 	}
-	if greet.Scope != ScopeProject || greet.Description != "project greet" {
-		t.Fatalf("project skill should win: got scope=%s desc=%q", greet.Scope, greet.Description)
+	if greet.Scope != ScopeCustom || greet.Description != "custom greet" {
+		t.Fatalf("custom skill should win over global: got scope=%s desc=%q", greet.Scope, greet.Description)
 	}
 	if _, ok := find(list, "onlyglobal"); !ok {
 		t.Fatal("global-only skill should be discovered")
@@ -66,14 +66,87 @@ func TestFlatAndDirLayout(t *testing.T) {
 	}
 }
 
+func TestNestedSkillsDiscoveredByDefault(t *testing.T) {
+	home := t.TempDir()
+	writeSkill(t, home, ".reasonix/skills/superpower/skill-a.md", "---\ndescription: nested flat\n---\nflat body")
+	writeSkill(t, home, ".reasonix/skills/superpower/tool-a/SKILL.md", "---\ndescription: nested dir\n---\ndir body")
+	writeSkill(t, home, ".reasonix/skills/superpower/references/notes.md", "---\ndescription: not a skill\n---\nnotes")
+
+	st := New(Options{HomeDir: home, DisableBuiltins: true})
+	list := st.List()
+	if _, ok := find(list, "skill-a"); !ok {
+		t.Fatal("default max depth should discover nested flat skills")
+	}
+	if _, ok := find(list, "tool-a"); !ok {
+		t.Fatal("default max depth should discover nested directory skills")
+	}
+	if _, ok := find(list, "notes"); ok {
+		t.Fatal("references directories should not be scanned as skill roots")
+	}
+	if sk, ok := st.Read("skill-a"); !ok || sk.Description != "nested flat" || !strings.Contains(sk.Body, "flat body") {
+		t.Fatalf("Read should resolve nested skills from the same discovery path: %+v ok=%v", sk, ok)
+	}
+}
+
+func TestMaxDepthOnePreservesRootOnlyDiscovery(t *testing.T) {
+	home := t.TempDir()
+	writeSkill(t, home, ".reasonix/skills/superpower/skill-a.md", "---\ndescription: nested flat\n---\nflat body")
+	writeSkill(t, home, ".reasonix/skills/superpower/tool-a/SKILL.md", "---\ndescription: nested dir\n---\ndir body")
+
+	st := New(Options{HomeDir: home, MaxDepth: 1, DisableBuiltins: true})
+	if _, ok := find(st.List(), "skill-a"); ok {
+		t.Fatal("max depth 1 should not discover nested flat skills")
+	}
+	if _, ok := find(st.List(), "tool-a"); ok {
+		t.Fatal("max depth 1 should not discover nested directory skills")
+	}
+}
+
+func TestNestedSkillsRequireDescription(t *testing.T) {
+	home := t.TempDir()
+	writeSkill(t, home, ".reasonix/skills/root.md", "---\n---\nroot body")
+	writeSkill(t, home, ".reasonix/skills/superpower/draft.md", "---\n---\ndraft body")
+	writeSkill(t, home, ".reasonix/skills/superpower/tool/SKILL.md", "---\n---\ntool body")
+
+	st := New(Options{HomeDir: home, DisableBuiltins: true})
+	list := st.List()
+	if _, ok := find(list, "root"); !ok {
+		t.Fatal("root-level skills without description should keep legacy discovery behavior")
+	}
+	if _, ok := find(list, "draft"); ok {
+		t.Fatal("nested flat skills without description should be ignored")
+	}
+	if _, ok := find(list, "tool"); ok {
+		t.Fatal("nested directory skills without description should be ignored")
+	}
+	if _, ok := st.Read("draft"); ok {
+		t.Fatal("Read should not resolve nested skills filtered for missing description")
+	}
+}
+
+func TestNestedDirectorySkillStopsTraversal(t *testing.T) {
+	home := t.TempDir()
+	writeSkill(t, home, ".reasonix/skills/pack/SKILL.md", "---\ndescription: pack\n---\npack body")
+	writeSkill(t, home, ".reasonix/skills/pack/child.md", "---\ndescription: child\n---\nchild body")
+
+	st := New(Options{HomeDir: home, MaxDepth: 3, DisableBuiltins: true})
+	if _, ok := find(st.List(), "pack"); !ok {
+		t.Fatal("directory-layout skill should be discovered")
+	}
+	if _, ok := find(st.List(), "child"); ok {
+		t.Fatal("directory-layout skill packages should not be scanned for child skills")
+	}
+}
+
 func TestConventionDirsDiscovered(t *testing.T) {
-	proj := t.TempDir()
-	writeSkill(t, proj, ".claude/skills/fromclaude.md", "---\ndescription: c\n---\nb")
-	writeSkill(t, proj, ".agents/skills/fromagents.md", "---\ndescription: a\n---\nb")
-	writeSkill(t, proj, ".agent/skills/fromagent.md", "---\ndescription: s\n---\nb")
-	st := New(Options{HomeDir: t.TempDir(), ProjectRoot: proj, DisableBuiltins: true})
+	home := t.TempDir()
+	writeSkill(t, home, ".claude/skills/fromclaude.md", "---\ndescription: c\n---\nb")
+	writeSkill(t, home, ".agents/skills/fromagents.md", "---\ndescription: a\n---\nb")
+	writeSkill(t, home, ".agent/skills/fromagent.md", "---\ndescription: s\n---\nb")
+	writeSkill(t, home, ".reasonix/skills/fromreasonix.md", "---\ndescription: r\n---\nb")
+	st := New(Options{HomeDir: home, DisableBuiltins: true})
 	list := st.List()
-	for _, name := range []string{"fromclaude", "fromagents", "fromagent"} {
+	for _, name := range []string{"fromclaude", "fromagents", "fromagent", "fromreasonix"} {
 		if _, ok := find(list, name); !ok {
 			t.Errorf("convention dir for %q not scanned", name)
 		}
@@ -166,7 +239,7 @@ func TestBuiltinSubagentSkillsDeclareAllowedTools(t *testing.T) {
 		if !sameStrings(sk.AllowedTools, want) {
 			t.Errorf("%s AllowedTools = %v, want %v", name, sk.AllowedTools, want)
 		}
-		for _, meta := range []string{"task", "run_skill", "install_skill", "explore", "research", "review", "security_review"} {
+		for _, meta := range []string{"task", "run_skill", "install_skill", "install_source", "explore", "research", "review", "security_review"} {
 			if containsString(sk.AllowedTools, meta) {
 				t.Errorf("%s AllowedTools should not include meta-tool %q: %v", name, meta, sk.AllowedTools)
 			}
@@ -189,6 +262,32 @@ func TestBuiltinsPresentAndOverridable(t *testing.T) {
 	}
 }
 
+func TestInstallCapabilityBuiltinIsInlineWithExpectedMetadata(t *testing.T) {
+	st := New(Options{HomeDir: t.TempDir()})
+	sk, ok := st.Read("install-capability")
+	if !ok {
+		t.Fatal("install-capability builtin skill must be registered")
+	}
+	if sk.Scope != ScopeBuiltin {
+		t.Errorf("install-capability scope = %s, want builtin", sk.Scope)
+	}
+	if sk.RunAs != RunInline {
+		t.Errorf("install-capability runAs = %s, want inline (it folds into the parent turn)", sk.RunAs)
+	}
+	if !strings.Contains(sk.Description, "install_source") {
+		t.Errorf("description should mention install_source, got %q", sk.Description)
+	}
+	if !strings.Contains(sk.Description, "uninstall") {
+		t.Errorf("description should advertise op=uninstall, got %q", sk.Description)
+	}
+	if !strings.Contains(sk.Body, "riskLevel") {
+		t.Error("body should mention the per-action riskLevel field so the model reads it")
+	}
+	if !strings.Contains(sk.Body, "planId") {
+		t.Error("body should mention the planId echo requirement on apply=true")
+	}
+}
+
 func TestDisabledSkillsAreFilteredFromListAndRead(t *testing.T) {
 	home := t.TempDir()
 	writeSkill(t, home, ".reasonix/skills/active.md", "---\ndescription: active\n---\nbody")
@@ -330,10 +429,15 @@ func TestCreateRefusesOverwrite(t *testing.T) {
 	if err != nil {
 		t.Fatalf("create: %v", err)
 	}
-	if !strings.HasSuffix(path, filepath.Join(".reasonix", "skills", "mine.md")) {
+	if !strings.HasSuffix(path, filepath.Join(".reasonix", "skills", "mine", SkillFile)) {
 		t.Errorf("unexpected path %q", path)
 	}
 	if _, err := st.Create("mine", ScopeGlobal); err == nil {
 		t.Error("second create should refuse to overwrite")
 	}
+
+	writeSkill(t, home, ".reasonix/skills/legacy.md", "---\ndescription: legacy\n---\nbody")
+	if _, err := st.Create("legacy", ScopeGlobal); err == nil {
+		t.Error("create should refuse to shadow an existing legacy flat skill")
+	}
 }
diff --git a/internal/skill/tools.go b/internal/skill/tools.go
index 7f5a2ff00..74aaad654 100644
--- a/internal/skill/tools.go
+++ b/internal/skill/tools.go
@@ -8,6 +8,7 @@ import (
 	"strconv"
 	"strings"
 
+	"reasonix/internal/event"
 	"reasonix/internal/tool"
 )
 
@@ -18,6 +19,10 @@ import (
 // silently inlining, which would lose the isolation the author asked for).
 type SubagentRunner func(ctx context.Context, sk Skill, task string) (string, error)
 
+// ProfileResolver returns the model/effort profile a subagent skill will use.
+// It is optional; without one, skill frontmatter still supplies display metadata.
+type ProfileResolver func(sk Skill) *event.Profile
+
 // InstalledHook fires after install_skill writes a new file, so a host can
 // refresh UI (e.g. a skills sidebar) without a reload. nil is fine.
 type InstalledHook func(name, path string, scope Scope)
@@ -25,14 +30,19 @@ type InstalledHook func(name, path string, scope Scope)
 // --- run_skill ---
 
 type runSkillTool struct {
-	store  *Store
-	runner SubagentRunner
+	store           *Store
+	runner          SubagentRunner
+	profileResolver ProfileResolver
 }
 
 // NewRunSkillTool builds the general skill-invocation tool. runner may be nil
 // (subagent skills then error).
-func NewRunSkillTool(store *Store, runner SubagentRunner) tool.Tool {
-	return &runSkillTool{store: store, runner: runner}
+func NewRunSkillTool(store *Store, runner SubagentRunner, profileResolver ...ProfileResolver) tool.Tool {
+	var pr ProfileResolver
+	if len(profileResolver) > 0 {
+		pr = profileResolver[0]
+	}
+	return &runSkillTool{store: store, runner: runner, profileResolver: pr}
 }
 
 func (*runSkillTool) Name() string { return "run_skill" }
@@ -87,6 +97,37 @@ func (t *runSkillTool) Execute(ctx context.Context, args json.RawMessage) (strin
 	return renderInline(sk, rawArgs), nil
 }
 
+func (t *runSkillTool) ResolveProfile(args json.RawMessage) *event.Profile {
+	var p struct {
+		Name string `json:"name"`
+	}
+	if err := json.Unmarshal(args, &p); err != nil {
+		return nil
+	}
+	name := cleanSkillName(p.Name)
+	if name == "" {
+		return nil
+	}
+	sk, ok := t.store.Read(name)
+	if !ok || sk.RunAs != RunSubagent {
+		return nil
+	}
+	return t.profileForSkill(sk)
+}
+
+func (t *runSkillTool) profileForSkill(sk Skill) *event.Profile {
+	if t.profileResolver != nil {
+		if pr := t.profileResolver(sk); pr != nil {
+			return pr
+		}
+	}
+	model, effort := strings.TrimSpace(sk.Model), strings.TrimSpace(sk.Effort)
+	if model == "" && effort == "" {
+		return nil
+	}
+	return &event.Profile{Model: model, Effort: effort}
+}
+
 // --- dedicated subagent wrappers (explore / research / review / security_review) ---
 
 type subagentSkillTool struct {
@@ -96,6 +137,7 @@ type subagentSkillTool struct {
 	taskDesc    string
 	store       *Store
 	runner      SubagentRunner
+	profile     ProfileResolver
 }
 
 func (t *subagentSkillTool) Name() string        { return t.toolName }
@@ -133,11 +175,32 @@ func (t *subagentSkillTool) Execute(ctx context.Context, args json.RawMessage) (
 	return t.runner(ctx, sk, task)
 }
 
+func (t *subagentSkillTool) ResolveProfile(json.RawMessage) *event.Profile {
+	sk, ok := t.store.Read(t.skillName)
+	if !ok || sk.RunAs != RunSubagent {
+		return nil
+	}
+	if t.profile != nil {
+		if pr := t.profile(sk); pr != nil {
+			return pr
+		}
+	}
+	model, effort := strings.TrimSpace(sk.Model), strings.TrimSpace(sk.Effort)
+	if model == "" && effort == "" {
+		return nil
+	}
+	return &event.Profile{Model: model, Effort: effort}
+}
+
 // BuiltinSubagentTools returns top-level wrapper tools for the built-in subagent
 // skills, named after the verb so the model picks them naturally (affordance >
 // prompt rules). Each is skipped when its underlying skill isn't present (e.g. a
 // user disabled it), so the tool set never advertises a phantom skill.
-func BuiltinSubagentTools(store *Store, runner SubagentRunner) []tool.Tool {
+func BuiltinSubagentTools(store *Store, runner SubagentRunner, profileResolver ...ProfileResolver) []tool.Tool {
+	var pr ProfileResolver
+	if len(profileResolver) > 0 {
+		pr = profileResolver[0]
+	}
 	specs := []struct {
 		toolName, skillName, description, taskDesc string
 	}{
@@ -166,6 +229,7 @@ func BuiltinSubagentTools(store *Store, runner SubagentRunner) []tool.Tool {
 			taskDesc:    s.taskDesc,
 			store:       store,
 			runner:      runner,
+			profile:     pr,
 		})
 	}
 	return out
@@ -187,23 +251,20 @@ func (*installSkillTool) Name() string   { return "install_skill" }
 func (*installSkillTool) ReadOnly() bool { return false }
 
 func (t *installSkillTool) Description() string {
-	scope := "'global' (only option — no project workspace) writes to ~/.reasonix/skills/."
-	if t.store.HasProjectScope() {
-		scope = "'project' (default) writes to <repo>/.reasonix/skills/ (this workspace only); 'global' writes to ~/.reasonix/skills/ (every project)."
-	}
-	return "Author and save a new skill — a reusable playbook future turns invoke via run_skill (or /<name>). Runnable immediately this turn; appears in the pinned Skills index on the next launch. " + scope
+	return "Author and save a new skill — a reusable playbook future turns invoke via run_skill (or /<name>). Runnable immediately this turn; appears in the pinned Skills index on the next launch. Scope: skills now live only in ~/.reasonix/skills/ (global) — project-scoped skills are no longer supported."
 }
 
 func (*installSkillTool) Schema() json.RawMessage {
 	return json.RawMessage(`{
 "type":"object",
 "properties":{
-  "name":{"type":"string","description":"Identifier — letters/digits/_/-/., 1-64 chars, starts alphanumeric. Becomes the filename."},
+  "name":{"type":"string","description":"Identifier — letters/digits/_/-/., 1-64 chars, starts alphanumeric. Becomes the skill folder name under ~/.reasonix/skills/<name>/SKILL.md."},
   "description":{"type":"string","description":"≤120-char one-liner shown in the pinned Skills index — future agents read it to decide whether to invoke."},
   "body":{"type":"string","description":"Markdown playbook. For subagent skills, write the subagent's persona/rules — it gets no context besides 'arguments' at runtime."},
-  "scope":{"type":"string","enum":["project","global"],"description":"Where to write. Defaults to project when a workspace exists, else global."},
+  "scope":{"type":"string","enum":["global"],"description":"Always global — skills are written to ~/.reasonix/skills/. Project-scoped skills are no longer supported."},
   "runAs":{"type":"string","enum":["inline","subagent"],"description":"inline (default) folds the body into the parent turn; subagent spawns an isolated child loop returning only its final answer (use for context-heavy work)."},
   "model":{"type":"string","description":"Optional model override for runAs=subagent (a configured provider/model name). Ignored otherwise."},
+  "effort":{"type":"string","description":"Optional effort for runAs=subagent (e.g. high, max). Ignored otherwise."},
   "allowedTools":{"type":"array","items":{"type":"string"},"description":"Optional tool allowlist for runAs=subagent (e.g. ['read_file','grep'])."}
 },
 "required":["name","description","body"]
@@ -218,6 +279,7 @@ func (t *installSkillTool) Execute(_ context.Context, args json.RawMessage) (str
 		Scope        string   `json:"scope"`
 		RunAs        string   `json:"runAs"`
 		Model        string   `json:"model"`
+		Effort       string   `json:"effort"`
 		AllowedTools []string `json:"allowedTools"`
 	}
 	if err := json.Unmarshal(args, &p); err != nil {
@@ -235,27 +297,20 @@ func (t *installSkillTool) Execute(_ context.Context, args json.RawMessage) (str
 		return "", fmt.Errorf("install_skill requires a non-empty 'body' — the playbook the skill executes")
 	}
 
-	scope := ScopeGlobal
 	switch strings.TrimSpace(p.Scope) {
 	case "global":
-		scope = ScopeGlobal
 	case "project":
-		scope = ScopeProject
+		return "", fmt.Errorf("install_skill: scope='project' is no longer supported — skills are only written to ~/.reasonix/skills/; use scope='global'")
 	default:
-		if t.store.HasProjectScope() {
-			scope = ScopeProject
-		}
-	}
-	if scope == ScopeProject && !t.store.HasProjectScope() {
-		return "", fmt.Errorf("install_skill: scope='project' requires a workspace — use scope='global'")
 	}
 
 	runAs := RunInline
 	if strings.TrimSpace(p.RunAs) == "subagent" {
 		runAs = RunSubagent
 	}
+	scope := ScopeGlobal
 
-	content := renderSkillFile(name, desc, p.Body, runAs, strings.TrimSpace(p.Model), p.AllowedTools)
+	content := renderSkillFile(name, desc, p.Body, runAs, strings.TrimSpace(p.Model), strings.TrimSpace(p.Effort), p.AllowedTools)
 	path, err := t.store.CreateWithContent(name, scope, content)
 	if err != nil {
 		return "", err
@@ -276,7 +331,7 @@ func (t *installSkillTool) Execute(_ context.Context, args json.RawMessage) (str
 
 // renderSkillFile assembles a skill file's frontmatter + body. Subagent-only
 // fields (model, allowed-tools) are emitted only when relevant.
-func renderSkillFile(name, desc, body string, runAs RunAs, model string, allowedTools []string) string {
+func renderSkillFile(name, desc, body string, runAs RunAs, model, effort string, allowedTools []string) string {
 	var fm strings.Builder
 	fm.WriteString("---\nname: " + name + "\ndescription: " + desc + "\n")
 	if runAs == RunSubagent {
@@ -284,6 +339,9 @@ func renderSkillFile(name, desc, body string, runAs RunAs, model string, allowed
 		if model != "" {
 			fm.WriteString("model: " + model + "\n")
 		}
+		if effort != "" {
+			fm.WriteString("effort: " + effort + "\n")
+		}
 		var tools []string
 		for _, t := range allowedTools {
 			if t = strings.TrimSpace(t); t != "" {
diff --git a/internal/skill/tools_test.go b/internal/skill/tools_test.go
index cf6710769..af74007df 100644
--- a/internal/skill/tools_test.go
+++ b/internal/skill/tools_test.go
@@ -3,8 +3,13 @@ package skill
 import (
 	"context"
 	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
 	"strings"
 	"testing"
+
+	"reasonix/internal/event"
 )
 
 func TestRunSkillInline(t *testing.T) {
@@ -61,6 +66,23 @@ func TestRunSkillSubagentRuns(t *testing.T) {
 	}
 }
 
+func TestRunSkillSubagentResolvesProfile(t *testing.T) {
+	home := t.TempDir()
+	writeSkill(t, home, ".reasonix/skills/deep.md", "---\ndescription: deep\nrunAs: subagent\nmodel: deepseek-pro\neffort: max\n---\nbody")
+	tl := NewRunSkillTool(New(Options{HomeDir: home, DisableBuiltins: true}), nil)
+
+	pr, ok := tl.(interface {
+		ResolveProfile(json.RawMessage) *event.Profile
+	})
+	if !ok {
+		t.Fatal("run_skill should expose ResolveProfile")
+	}
+	got := pr.ResolveProfile(json.RawMessage(`{"name":"deep","arguments":"x"}`))
+	if got == nil || got.Model != "deepseek-pro" || got.Effort != "max" {
+		t.Fatalf("profile = %+v, want deepseek-pro/max", got)
+	}
+}
+
 func TestRunSkillSubagentRequiresArgs(t *testing.T) {
 	home := t.TempDir()
 	writeSkill(t, home, ".reasonix/skills/dig.md", "---\ndescription: dig\nrunAs: subagent\n---\nbody")
@@ -114,26 +136,67 @@ func TestBuiltinSubagentToolsRunner(t *testing.T) {
 	}
 }
 
+func TestBuiltinSubagentToolResolvesProfile(t *testing.T) {
+	store := New(Options{HomeDir: t.TempDir()})
+	tools := BuiltinSubagentTools(store, nil, func(sk Skill) *event.Profile {
+		return &event.Profile{Model: sk.Name + "-model", Effort: "max"}
+	})
+	var review interface {
+		ResolveProfile(json.RawMessage) *event.Profile
+	}
+	for _, tl := range tools {
+		if tl.Name() == "review" {
+			review = tl.(interface {
+				ResolveProfile(json.RawMessage) *event.Profile
+			})
+			break
+		}
+	}
+	if review == nil {
+		t.Fatal("review tool not found")
+	}
+	got := review.ResolveProfile(json.RawMessage(`{"task":"general"}`))
+	if got == nil || got.Model != "review-model" || got.Effort != "max" {
+		t.Fatalf("profile = %+v, want review-model/max", got)
+	}
+}
+
 func TestInstallSkill(t *testing.T) {
 	home := t.TempDir()
 	st := New(Options{HomeDir: home, DisableBuiltins: true})
 	tl := NewInstallSkillTool(st, nil)
 
 	out, err := tl.Execute(context.Background(), json.RawMessage(
-		`{"name":"deploy","description":"ship it","body":"steps","runAs":"subagent","allowedTools":["bash","read_file"]}`))
+		`{"name":"deploy","description":"ship it","body":"steps","runAs":"subagent","model":"deepseek-pro","effort":"max","allowedTools":["bash","read_file"]}`))
 	if err != nil {
 		t.Fatalf("execute: %v", err)
 	}
 	if !strings.Contains(out, `"ok":true`) {
 		t.Errorf("expected ok result, got %s", out)
 	}
+	var res struct {
+		Path string `json:"path"`
+	}
+	if err := json.Unmarshal([]byte(out), &res); err != nil {
+		t.Fatalf("result JSON: %v", err)
+	}
+	wantPath := filepath.Join(home, ".reasonix", "skills", "deploy", SkillFile)
+	if res.Path != wantPath {
+		t.Fatalf("install_skill should report canonical path %s, got %s", wantPath, res.Path)
+	}
+	if _, err := os.Stat(wantPath); err != nil {
+		t.Fatalf("install_skill should write canonical SKILL.md: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(home, ".reasonix", "skills", "deploy.md")); !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("install_skill should not write legacy flat deploy.md, stat err=%v", err)
+	}
 	// Round-trips through the store with the frontmatter we wrote.
 	sk, ok := st.Read("deploy")
 	if !ok {
 		t.Fatal("installed skill not readable")
 	}
-	if sk.RunAs != RunSubagent || len(sk.AllowedTools) != 2 {
-		t.Errorf("frontmatter not round-tripped: runAs=%s tools=%v", sk.RunAs, sk.AllowedTools)
+	if sk.RunAs != RunSubagent || sk.Model != "deepseek-pro" || sk.Effort != "max" || len(sk.AllowedTools) != 2 {
+		t.Errorf("frontmatter not round-tripped: runAs=%s model=%q effort=%q tools=%v", sk.RunAs, sk.Model, sk.Effort, sk.AllowedTools)
 	}
 	// Refuses overwrite.
 	if _, err := tl.Execute(context.Background(), json.RawMessage(
diff --git a/reasonix.example.toml b/reasonix.example.toml
index ca14191f6..9189f2575 100644
--- a/reasonix.example.toml
+++ b/reasonix.example.toml
@@ -104,12 +104,11 @@ enabled = []   # empty = all built-in tools
 # trace / node tools. Off by default for first-run sessions. Once enabled, the
 # runtime is fetched into a per-version cache when missing (auto_install);
 # .codegraph/ is then initialised (fast) and CodeGraph's daemon indexes in the
-# background. Choose tier the same way as ordinary MCP servers.
+# background once enabled.
 # [codegraph]
 # enabled      = false
 # auto_install = true
 # path         = ""   # empty = cache, then PATH, then a bundle beside reasonix
-# tier         = "lazy"   # lazy | background | eager
 
 # Skills are invokable playbooks (SKILL.md / <name>.md with frontmatter), found
 # under .reasonix/skills, .agents/skills, .agent/skills, .claude/skills (project)
@@ -140,11 +139,5 @@ enabled = []   # empty = all built-in tools
 # [[plugins]]
 # name    = "example"
 # command = "reasonix-plugin-example"
-# tier    = "lazy"  # eager | lazy (default) | background
-# # tier guidance:
-# #   eager      — handshake at boot; the agent waits. Use when the plugin's
-# #                tools must be in the very first turn's system prompt.
-# #   lazy       — placeholder tools (from cached schema, when present) until
-# #                the model uses them, then handshake on-demand. Default.
-# #   background — placeholder + spawn at boot in a goroutine so an idle
-# #                session warms up without blocking the user.
+# # Enabled MCP servers connect automatically in the background after session
+# # start. Use /mcp or the desktop MCP panel to refresh, reconnect, or disable.