From f4c3354faf072589070644d6c3daa8da4c6f3775 Mon Sep 17 00:00:00 2001
From: Lakshman Patel <Lakshmanp230@gmail.com>
Date: Sat, 20 Jun 2026 10:36:12 +0530
Subject: [PATCH 1/3] feat(storage): add storage policy cleanup and centralize
 hawk data paths

Introduce internal/storage helpers with policy tests, route session and
plugin persistence through the shared layout, and trim duplicated path
handling across cmd and internal packages.
---
 cmd/agent.go                                  |   2 +-
 cmd/audit.go                                  |   8 +-
 cmd/bg_sessions.go                            |   5 +-
 cmd/chat.go                                   |  13 +-
 cmd/chat_commands_session.go                  |  14 +-
 cmd/chat_commands_util.go                     |   2 +-
 cmd/chat_focus.go                             |   4 +-
 cmd/chat_subcommand_memory.go                 |   6 +-
 cmd/chat_subcommand_recipe.go                 |   2 +-
 cmd/chat_subcommand_simple.go                 |  11 +-
 cmd/chat_tools.go                             |  16 --
 cmd/cmdhistory_cmd.go                         |   7 +-
 cmd/daemon.go                                 |  10 +-
 cmd/diagnostics.go                            |  10 +-
 cmd/dx.go                                     |   5 +-
 cmd/errors.go                                 |  52 +++----
 cmd/exec.go                                   |   5 +-
 cmd/exec_test.go                              |   9 +-
 cmd/feedback.go                               |  10 +-
 cmd/history.go                                |   9 +-
 cmd/history_test.go                           |   6 +-
 cmd/manpage.go                                |   8 +-
 cmd/permissions_center.go                     |  15 +-
 cmd/plan.go                                   |  28 ++--
 cmd/review.go                                 |   4 -
 cmd/review_store.go                           |   8 +-
 cmd/root.go                                   |   4 +-
 cmd/rules.go                                  |   4 +-
 cmd/storage_policy_test.go                    |  33 ++++
 cmd/tips.go                                   |   8 +-
 external/eyrie                                |   2 +-
 internal/auth/auth.go                         |  20 +--
 internal/auth/auth_test.go                    |  26 +---
 internal/autoinit/autoinit.go                 |   7 +-
 internal/config/config.go                     |  18 +--
 internal/config/config_test.go                |  84 ++--------
 internal/config/credentials_store.go          |   8 +-
 internal/config/deployments_ui.go             |  25 +--
 internal/config/settings.go                   |  54 +------
 internal/config/xiaomi_setup_test.go          |   2 +
 internal/context/rules.go                     |  10 +-
 internal/context/rules_test.go                |  16 +-
 internal/daemon/daemon.go                     |   5 +-
 internal/daemon/routes_sessions.go            |  13 +-
 internal/engine/adaptive_prompt.go            |   7 +-
 internal/engine/bmad_features_test.go         |   3 +-
 internal/engine/coding_soul.go                |  16 +-
 internal/engine/compact/session_memory.go     |   7 +-
 internal/engine/context_compaction.go         |   6 +-
 internal/engine/context_governor_test.go      |   3 +-
 internal/engine/cost/cost_tracker.go          |   8 +-
 internal/engine/errs/error_context.go         |   2 +-
 internal/engine/errs/error_patterns.go        |   5 +-
 internal/engine/hints_loader.go               |   2 +-
 internal/engine/integration.go                |  10 +-
 internal/engine/lifecycle_service.go          |   4 +-
 internal/engine/multi_repo.go                 |   6 +-
 internal/engine/project/project_context.go    |  10 +-
 internal/engine/prompt/prompt_optimizer.go    |   5 +-
 internal/engine/prompt/prompt_tuner.go        |   5 +-
 internal/engine/scaffold/fewshot.go           |   7 +-
 internal/engine/self_improve.go               |   5 +-
 internal/engine/session.go                    |   2 +-
 internal/engine/stream_tool_exec.go           |   2 +-
 internal/engine/tool_output_spill.go          |   6 +-
 internal/engine/transfer.go                   |   7 +-
 internal/feature/eval/cache.go                |   7 +-
 internal/feature/eval/store.go                |   7 +-
 internal/feature/shellmode/modes.go           |  14 +-
 internal/feature/taste/store.go               |  13 +-
 internal/hooks/hooks.go                       |  18 +--
 internal/intelligence/memory/auto_memory.go   |   7 +-
 internal/intelligence/memory/autodream.go     |   5 +-
 internal/intelligence/memory/autofile.go      |   4 +-
 internal/intelligence/memory/evolving.go      |   7 +-
 internal/intelligence/memory/memory.go        |   5 +-
 internal/intelligence/memory/memory_test.go   |   7 +-
 internal/intelligence/memory/zenbrain.go      |   5 +-
 internal/intelligence/planner/planner.go      |   8 +-
 .../intelligence/repomap/incremental_map.go   |  11 +-
 internal/intelligence/repomap/patterns.go     |  24 +--
 internal/lsp/config.go                        |  11 +-
 internal/multiagent/agents/agents.go          |  24 +--
 internal/multiagent/agents/agents_test.go     |   7 +-
 internal/multiagent/agents/persona.go         |   7 +-
 .../agents/persona_registry_test.go           |  10 +-
 .../multiagent/parallel/worktree_manager.go   |   6 +-
 internal/observability/analytics.go           |   5 +-
 internal/observability/analytics_test.go      |   5 +-
 internal/observability/insights.go            |   8 +-
 internal/permissions/persist.go               |   4 +-
 internal/permissions/rules_test.go            |   2 +-
 internal/plugin/auto_skill.go                 |   4 +-
 internal/plugin/auto_skill_audit_test.go      |   6 +-
 internal/plugin/bundled_skills.go             |   5 +-
 internal/plugin/dynamic.go                    |   9 +-
 internal/plugin/feedback.go                   |   7 +-
 internal/plugin/manager.go                    |   8 +-
 internal/plugin/manager_test.go               |  12 +-
 internal/plugin/plugin.go                     |   5 +-
 internal/plugin/registry.go                   |  20 +--
 internal/plugin/skills_auto.go                |  12 +-
 internal/plugin/wizard.go                     |   6 +-
 internal/prompts/agents_accumulator.go        |  13 +-
 internal/prompts/agents_accumulator_test.go   |   4 +-
 internal/prompts/loader.go                    |  15 +-
 internal/recipe/providers.go                  |   7 +-
 internal/recipe/recipe.go                     |   7 +-
 internal/resilience/health/diagnostics.go     |  41 +----
 internal/rules/formats.go                     |   6 +-
 internal/rules/formats_test.go                |   2 +-
 internal/rules/rules.go                       |   4 +-
 internal/rules/rules_test.go                  |   8 +-
 internal/sandbox/approval.go                  |   7 +-
 internal/sandbox/container.go                 |  12 +-
 internal/sandbox/container_test.go            |   9 +-
 internal/sandbox/manager.go                   |   9 +-
 internal/sandbox/manager_test.go              |   8 +-
 internal/sandbox/mode.go                      |  14 +-
 internal/sandbox/runtime_deps.go              |   6 +-
 internal/sandbox/runtime_deps_test.go         |   4 +-
 internal/session/autosave_test.go             |  16 +-
 internal/session/benchmark_test.go            |   4 +-
 internal/session/export_redact_test.go        |   4 +-
 internal/session/persist.go                   |   6 +-
 internal/session/persist_integrity_test.go    |  15 +-
 internal/session/session.go                   |  23 ++-
 internal/session/session_concurrent_test.go   |   6 +-
 internal/session/session_safety_test.go       |  18 ++-
 internal/session/snapshot.go                  |   5 +-
 internal/session/storage_policy_test.go       |  25 +++
 internal/session/storage_test_helpers_test.go |  13 ++
 internal/snapshot/snapshot.go                 |   6 +-
 internal/snapshot/workspace.go                |   6 +-
 internal/snapshot/workspace_test.go           |  11 +-
 internal/storage/paths.go                     | 147 ++++++++++++++++++
 internal/storage/paths_test.go                |  58 +++++++
 internal/tool/audit.go                        |   8 +-
 internal/tool/backup.go                       |   8 +-
 internal/tool/devenv.go                       |   5 +-
 internal/tool/safety.go                       |   6 +
 internal/tool/skill.go                        |  15 +-
 internal/tool/tool_test.go                    |   4 +-
 internal/tool/treesitter.go                   |   4 +-
 internal/tool/workflow.go                     |  34 ++--
 lefthook.yml                                  |   2 +-
 146 files changed, 843 insertions(+), 843 deletions(-)
 create mode 100644 cmd/storage_policy_test.go
 create mode 100644 internal/session/storage_policy_test.go
 create mode 100644 internal/session/storage_test_helpers_test.go
 create mode 100644 internal/storage/paths.go
 create mode 100644 internal/storage/paths_test.go

diff --git a/cmd/agent.go b/cmd/agent.go
index ff4ecce7..8c4ad462 100644
--- a/cmd/agent.go
+++ b/cmd/agent.go
@@ -15,7 +15,7 @@ import (
 var agentCmd = &cobra.Command{
 	Use:   "agent",
 	Short: "Manage custom agent personas",
-	Long:  "Create, list, and manage custom agent personas stored in ~/.hawk/agents/.",
+	Long:  "Create, list, and manage custom agent personas stored in Hawk user state.",
 }
 
 var agentListCmd = &cobra.Command{
diff --git a/cmd/audit.go b/cmd/audit.go
index d3c9d537..e3332bf6 100644
--- a/cmd/audit.go
+++ b/cmd/audit.go
@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/GrayCodeAI/hawk/internal/hooks/audit"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/spf13/cobra"
 )
 
@@ -175,16 +176,11 @@ type SessionInfo struct {
 }
 
 func discoverSessions(days int, projectFilter string) ([]SessionInfo, error) {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return nil, err
-	}
-
 	cutoff := time.Now().AddDate(0, 0, -days)
 	var sessions []SessionInfo
 
 	// Scan hawk sessions directory
-	hawkDir := filepath.Join(home, ".hawk", "sessions")
+	hawkDir := storage.SessionsDir()
 	entries, err := os.ReadDir(hawkDir)
 	if err != nil && !os.IsNotExist(err) {
 		return nil, err
diff --git a/cmd/bg_sessions.go b/cmd/bg_sessions.go
index 1ea3357b..c4822cd5 100644
--- a/cmd/bg_sessions.go
+++ b/cmd/bg_sessions.go
@@ -10,7 +10,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/spf13/cobra"
 )
 
@@ -19,8 +19,7 @@ import (
 // ─────────────────────────────────────────────────────────────────────────────
 
 func bgSessionsDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "bg-sessions")
+	return filepath.Join(storage.StateDir(), "bg-sessions")
 }
 
 // BGSessionInfo tracks a running background session.
diff --git a/cmd/chat.go b/cmd/chat.go
index c6c8bb22..2f658f3c 100644
--- a/cmd/chat.go
+++ b/cmd/chat.go
@@ -30,7 +30,6 @@ import (
 	"github.com/GrayCodeAI/hawk/internal/engine"
 	"github.com/GrayCodeAI/hawk/internal/feature/shellmode"
 	"github.com/GrayCodeAI/hawk/internal/feature/taste"
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/intelligence/memory"
 	"github.com/GrayCodeAI/hawk/internal/intelligence/repomap"
 	"github.com/GrayCodeAI/hawk/internal/observability/logger"
@@ -38,6 +37,7 @@ import (
 	"github.com/GrayCodeAI/hawk/internal/sandbox"
 	"github.com/GrayCodeAI/hawk/internal/session"
 	"github.com/GrayCodeAI/hawk/internal/startup"
+	hawkstorage "github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/system/staleness"
 	"github.com/GrayCodeAI/hawk/internal/ui/icons"
 )
@@ -152,11 +152,9 @@ func newChatModel(ref *progRef, systemPrompt string, settings hawkconfig.Setting
 
 	// Initialize conversation DAG for branching support
 	startup.MarkPhase("newChatModel:dag")
-	if home, err := os.UserHomeDir(); err == nil {
-		dagPath := filepath.Join(home, ".hawk", "sessions", "convo.db")
-		if dag, err := storage.NewDAG(dagPath, sid); err == nil {
-			sess.SetConvoDAG(dag)
-		}
+	dagPath := filepath.Join(hawkstorage.SessionsDir(), "convo.db")
+	if dag, err := storage.NewDAG(dagPath, sid); err == nil {
+		sess.SetConvoDAG(dag)
 	}
 	startup.EndPhase("newChatModel:dag")
 
@@ -241,8 +239,7 @@ func newChatModel(ref *progRef, systemPrompt string, settings hawkconfig.Setting
 	// Check for crash recovery
 	startup.MarkPhase("newChatModel:crash-recovery")
 	if recovered := session.CheckForRecovery(); len(recovered) > 0 {
-		home := home.Dir()
-		walDir := filepath.Join(home, ".hawk", "sessions")
+		walDir := hawkstorage.SessionsDir()
 		for _, rid := range recovered {
 			if rid == sid {
 				continue // current session WAL
diff --git a/cmd/chat_commands_session.go b/cmd/chat_commands_session.go
index e1330f41..e2ea8680 100644
--- a/cmd/chat_commands_session.go
+++ b/cmd/chat_commands_session.go
@@ -12,8 +12,8 @@ import (
 	tea "github.com/charmbracelet/bubbletea"
 
 	"github.com/GrayCodeAI/eyrie/client"
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/session"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // saveSession persists the current session to disk.
@@ -234,8 +234,7 @@ func (m *chatModel) handleSessionCommand(cmd string, parts []string, text string
 		return m, nil
 
 	case "/export":
-		homeDir := home.Dir()
-		exportDir := filepath.Join(homeDir, ".hawk", "exports")
+		exportDir := filepath.Join(storage.StateDir(), "exports")
 		_ = os.MkdirAll(exportDir, 0o755)
 		exportPath := filepath.Join(exportDir, m.sessionID+".md")
 		var md strings.Builder
@@ -258,8 +257,7 @@ func (m *chatModel) handleSessionCommand(cmd string, parts []string, text string
 		return m, nil
 
 	case "/share":
-		homeDir := home.Dir()
-		exportDir := filepath.Join(homeDir, ".hawk", "exports")
+		exportDir := filepath.Join(storage.StateDir(), "exports")
 		_ = os.MkdirAll(exportDir, 0o755)
 		exportPath := filepath.Join(exportDir, m.sessionID+".md")
 		var md strings.Builder
@@ -286,8 +284,7 @@ func (m *chatModel) handleSessionCommand(cmd string, parts []string, text string
 			return m, nil
 		}
 		newName := parts[1]
-		homeDir := home.Dir()
-		sessDir := filepath.Join(homeDir, ".hawk", "sessions")
+		sessDir := storage.SessionsDir()
 		oldPath := filepath.Join(sessDir, m.sessionID+".jsonl")
 		newPath := filepath.Join(sessDir, newName+".jsonl")
 		if err := os.Rename(oldPath, newPath); err != nil {
@@ -303,8 +300,7 @@ func (m *chatModel) handleSessionCommand(cmd string, parts []string, text string
 			m.messages = append(m.messages, displayMsg{role: "system", content: "Usage: /tag <label>"})
 			return m, nil
 		}
-		homeDir := home.Dir()
-		tagFile := filepath.Join(homeDir, ".hawk", "sessions", m.sessionID+".tags")
+		tagFile := filepath.Join(storage.SessionsDir(), m.sessionID+".tags")
 		f, err := os.OpenFile(tagFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
 		if err != nil {
 			m.messages = append(m.messages, displayMsg{role: "error", content: err.Error()})
diff --git a/cmd/chat_commands_util.go b/cmd/chat_commands_util.go
index cbb8133d..9bcaf55a 100644
--- a/cmd/chat_commands_util.go
+++ b/cmd/chat_commands_util.go
@@ -127,7 +127,7 @@ func sessionStats(sess *engine.Session, id string) string {
 }
 
 func hooksSummary() string {
-	return "Hooks: pre_query, post_query, pre_tool, post_tool, session_start, session_end, permission_ask, error\nConfigure in .hawk/settings.json or ~/.hawk/settings.json"
+	return "Hooks: pre_query, post_query, pre_tool, post_tool, session_start, session_end, permission_ask, error\nConfigure in Hawk user settings"
 }
 
 func pluginsSummary(rt *plugin.Runtime) string {
diff --git a/cmd/chat_focus.go b/cmd/chat_focus.go
index 1eb9c317..3982ad8b 100644
--- a/cmd/chat_focus.go
+++ b/cmd/chat_focus.go
@@ -10,7 +10,7 @@ import (
 	tea "github.com/charmbracelet/bubbletea"
 
 	"github.com/GrayCodeAI/hawk/internal/engine"
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/ui/icons"
 )
 
@@ -25,7 +25,7 @@ const (
 const toolDisplayMaxChars = 12000 // preview cap in scrollback (Grok uses ~20k for bash)
 
 func sessionExportPath(sessionID string) string {
-	return filepath.Join(home.Dir(), ".hawk", "exports", sessionID+".md")
+	return filepath.Join(storage.StateDir(), "exports", sessionID+".md")
 }
 
 func (m *chatModel) inScrollbackFocus() bool {
diff --git a/cmd/chat_subcommand_memory.go b/cmd/chat_subcommand_memory.go
index fbc365b5..4d9fffc7 100644
--- a/cmd/chat_subcommand_memory.go
+++ b/cmd/chat_subcommand_memory.go
@@ -8,8 +8,8 @@ import (
 	hawkconfig "github.com/GrayCodeAI/hawk/internal/config"
 )
 
-// memorySubcommand implements the /memory slash command. It
-// prints the project's AGENTS.md (or .hawk/AGENTS.md) content.
+// memorySubcommand implements the /memory slash command.
+// It prints the project's AGENTS.md content.
 type memorySubcommand struct{}
 
 func (m *memorySubcommand) Name() string        { return "memory" }
@@ -19,7 +19,7 @@ func (m *memorySubcommand) Usage() string       { return "" }
 func (m *memorySubcommand) Handle(ml *chatModel, args []string, text string) (tea.Model, tea.Cmd) {
 	md := strings.TrimSpace(hawkconfig.LoadAgentsMD())
 	if md == "" {
-		ml.messages = append(ml.messages, displayMsg{role: "system", content: "No AGENTS.md or .hawk/AGENTS.md project instructions found.\nUse /yaad for persistent graph memory."})
+		ml.messages = append(ml.messages, displayMsg{role: "system", content: "No AGENTS.md project instructions found.\nUse /yaad for persistent graph memory."})
 	} else {
 		ml.messages = append(ml.messages, displayMsg{role: "system", content: "Project instructions (AGENTS.md):\n" + md})
 	}
diff --git a/cmd/chat_subcommand_recipe.go b/cmd/chat_subcommand_recipe.go
index fdb4d6ef..1471d600 100644
--- a/cmd/chat_subcommand_recipe.go
+++ b/cmd/chat_subcommand_recipe.go
@@ -25,7 +25,7 @@ func (r *recipeSubcommand) Handle(m *chatModel, args []string, text string) (tea
 		rn := recipe.NewRunner()
 		recipes := rn.List()
 		if len(recipes) == 0 {
-			m.messages = append(m.messages, displayMsg{role: "system", content: "No recipes found in ~/.hawk/recipes/ or .hawk/recipes/"})
+			m.messages = append(m.messages, displayMsg{role: "system", content: "No recipes found in Hawk user state or .agents/recipes/"})
 		} else {
 			var list string
 			for _, r := range recipes {
diff --git a/cmd/chat_subcommand_simple.go b/cmd/chat_subcommand_simple.go
index 965494aa..14b2681c 100644
--- a/cmd/chat_subcommand_simple.go
+++ b/cmd/chat_subcommand_simple.go
@@ -12,9 +12,9 @@ import (
 	tea "github.com/charmbracelet/bubbletea"
 
 	hawkconfig "github.com/GrayCodeAI/hawk/internal/config"
-	"github.com/GrayCodeAI/hawk/internal/home"
 	analytics "github.com/GrayCodeAI/hawk/internal/observability"
 	"github.com/GrayCodeAI/hawk/internal/plugin"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/tool"
 )
 
@@ -645,19 +645,18 @@ func init() {
 		},
 	})
 
-	// /feedback <msg> — submit feedback saved to ~/.hawk/feedback/
+	// /feedback <msg> — submit feedback saved to Hawk user state.
 	subcommandRegistry.Register(&delegatingCommand{
 		name:        "feedback",
-		description: "submit feedback (saved to ~/.hawk/feedback/)",
+		description: "submit feedback (saved to Hawk user state)",
 		usage:       "/feedback <message>",
 		handler: func(m *chatModel, args []string, text string) (tea.Model, tea.Cmd) {
 			body := strings.TrimSpace(strings.TrimPrefix(text, "/feedback"))
 			if body == "" {
-				m.messages = append(m.messages, displayMsg{role: "system", content: "Usage: /feedback <message>\nCaptures session context and saves feedback to ~/.hawk/feedback/"})
+				m.messages = append(m.messages, displayMsg{role: "system", content: "Usage: /feedback <message>\nCaptures session context and saves feedback to Hawk user state."})
 				return m, nil
 			}
-			homeDir := home.Dir()
-			feedDir := filepath.Join(homeDir, ".hawk", "feedback")
+			feedDir := filepath.Join(storage.StateDir(), "feedback")
 			_ = os.MkdirAll(feedDir, 0o755)
 			report := fmt.Sprintf(`{"timestamp":%q,"version":%q,"model":%q,"provider":%q,"category":"session","body":%q,"session_id":%q}`,
 				time.Now().Format(time.RFC3339), version, m.session.Model(), m.session.Provider(), body, m.sessionID)
diff --git a/cmd/chat_tools.go b/cmd/chat_tools.go
index f8710650..d3288b69 100644
--- a/cmd/chat_tools.go
+++ b/cmd/chat_tools.go
@@ -2,8 +2,6 @@ package cmd
 
 import (
 	"context"
-	"fmt"
-	"os"
 	"strings"
 
 	hawkconfig "github.com/GrayCodeAI/hawk/internal/config"
@@ -85,24 +83,10 @@ func defaultRegistry(settings hawkconfig.Settings) (*tool.Registry, error) {
 	if tool.IsPowerShellAvailable() {
 		tools = append(tools, tool.PowerShellTool{})
 	}
-	// Detect project-level MCP servers (supply chain attack vector).
-	// Project .hawk/settings.json can be committed to a repo and define
-	// arbitrary commands that execute on clone. Gate behind --allow-project-mcp.
-	projectMCPServers := hawkconfig.ProjectMCPServers()
-	projectMCPNames := make(map[string]bool, len(projectMCPServers))
-	for _, cfg := range projectMCPServers {
-		if cfg.Name != "" {
-			projectMCPNames[cfg.Name] = true
-		}
-	}
 	for _, cfg := range settings.MCPServers {
 		if cfg.Name == "" || cfg.Command == "" {
 			continue
 		}
-		if projectMCPNames[cfg.Name] && !allowProjectMCP {
-			fmt.Fprintf(os.Stderr, "hawk: skipping project-level MCP server %q (defined in .hawk/settings.json); use --allow-project-mcp to enable\n", cfg.Name)
-			continue
-		}
 		mcpTools, err := tool.LoadMCPTools(context.Background(), cfg.Name, cfg.Command, cfg.Args...)
 		if err != nil {
 			continue
diff --git a/cmd/cmdhistory_cmd.go b/cmd/cmdhistory_cmd.go
index a7416fd6..3fb27986 100644
--- a/cmd/cmdhistory_cmd.go
+++ b/cmd/cmdhistory_cmd.go
@@ -7,6 +7,7 @@ import (
 	"strconv"
 
 	"github.com/GrayCodeAI/hawk/internal/cmdhistory"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/spf13/cobra"
 )
 
@@ -158,11 +159,7 @@ func init() {
 }
 
 func openCmdHistoryStore() (*cmdhistory.Store, error) {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return nil, fmt.Errorf("cannot determine home directory: %w", err)
-	}
-	dbPath := filepath.Join(home, ".hawk", "cmd-history.db")
+	dbPath := filepath.Join(storage.StateDir(), "cmd-history.db")
 
 	// Ensure the directory exists.
 	if mkErr := os.MkdirAll(filepath.Dir(dbPath), 0o755); mkErr != nil {
diff --git a/cmd/daemon.go b/cmd/daemon.go
index 7963b16a..19eb9f81 100644
--- a/cmd/daemon.go
+++ b/cmd/daemon.go
@@ -17,9 +17,9 @@ import (
 	hawkconfig "github.com/GrayCodeAI/hawk/internal/config"
 	"github.com/GrayCodeAI/hawk/internal/daemon"
 	"github.com/GrayCodeAI/hawk/internal/engine"
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/netutil"
 	"github.com/GrayCodeAI/hawk/internal/observability/logger"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/spf13/cobra"
 )
 
@@ -130,7 +130,7 @@ func runDaemonStart(_ *cobra.Command, _ []string) error {
 	} else {
 		fmt.Println("API key: (set via --api-key or HAWK_DAEMON_API_KEY)")
 	}
-	keyFile := filepath.Join(home.Dir(), ".hawk", "run", "daemon.key")
+	keyFile := filepath.Join(storage.DaemonRunDir(), "daemon.key")
 	_ = os.MkdirAll(filepath.Dir(keyFile), 0o700)
 	if err := os.WriteFile(keyFile, []byte(apiKey), 0o600); err == nil {
 		fmt.Printf("Full API key written to %s\n", keyFile)
@@ -202,8 +202,7 @@ func generateDaemonAPIKey() (string, error) {
 }
 
 func runDaemonStop(_ *cobra.Command, _ []string) error {
-	home := home.Dir()
-	pidFile := filepath.Join(home, ".hawk", "run", "daemon.json")
+	pidFile := filepath.Join(storage.DaemonRunDir(), "daemon.json")
 
 	data, err := os.ReadFile(pidFile)
 	if err != nil {
@@ -233,8 +232,7 @@ func runDaemonStop(_ *cobra.Command, _ []string) error {
 }
 
 func runDaemonStatus(_ *cobra.Command, _ []string) error {
-	home := home.Dir()
-	pidFile := filepath.Join(home, ".hawk", "run", "daemon.json")
+	pidFile := filepath.Join(storage.DaemonRunDir(), "daemon.json")
 
 	data, err := os.ReadFile(pidFile)
 	if err != nil {
diff --git a/cmd/diagnostics.go b/cmd/diagnostics.go
index b04dd4ff..8b0d28fc 100644
--- a/cmd/diagnostics.go
+++ b/cmd/diagnostics.go
@@ -20,6 +20,7 @@ import (
 	"github.com/GrayCodeAI/hawk/internal/plugin"
 	"github.com/GrayCodeAI/hawk/internal/resilience/health"
 	"github.com/GrayCodeAI/hawk/internal/session"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/ui/icons"
 )
 
@@ -151,20 +152,13 @@ func healthCheckReport(settings hawkconfig.Settings, provider string) string {
 	// Config syntax check
 	registry.Register("config_syntax", func(ctx context.Context) health.Check {
 		start := time.Now()
-		home, _ := os.UserHomeDir()
-		globalPath := filepath.Join(home, ".hawk", "settings.json")
+		globalPath := storage.SettingsPath()
 		if data, err := os.ReadFile(globalPath); err == nil {
 			var raw json.RawMessage
 			if err := json.Unmarshal(data, &raw); err != nil {
 				return health.Check{Name: "config_syntax", Status: health.Unhealthy, Message: fmt.Sprintf("global settings.json parse error: %v", err), Duration: time.Since(start)}
 			}
 		}
-		if data, err := os.ReadFile(".hawk/settings.json"); err == nil {
-			var raw json.RawMessage
-			if err := json.Unmarshal(data, &raw); err != nil {
-				return health.Check{Name: "config_syntax", Status: health.Unhealthy, Message: fmt.Sprintf("project settings.json parse error: %v", err), Duration: time.Since(start)}
-			}
-		}
 		return health.Check{Name: "config_syntax", Status: health.Healthy, Message: "config files parse OK", Duration: time.Since(start)}
 	})
 
diff --git a/cmd/dx.go b/cmd/dx.go
index 0223dc08..ed5dbd8b 100644
--- a/cmd/dx.go
+++ b/cmd/dx.go
@@ -12,8 +12,8 @@ import (
 
 	hawkconfig "github.com/GrayCodeAI/hawk/internal/config"
 	"github.com/GrayCodeAI/hawk/internal/engine"
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/plugin"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // startTime records when the process started, used by debugOutput for uptime.
@@ -78,8 +78,7 @@ func doctorOutput(settings hawkconfig.Settings) string {
 
 	// Session directory status
 	b.WriteString("\nSession directory:\n")
-	home := home.Dir()
-	sessDir := filepath.Join(home, ".hawk", "sessions")
+	sessDir := storage.SessionsDir()
 	if info, err := os.Stat(sessDir); err != nil {
 		b.WriteString(fmt.Sprintf("  Status:      missing (%s)\n", sessDir))
 	} else if !info.IsDir() {
diff --git a/cmd/errors.go b/cmd/errors.go
index ceddc740..1657b02e 100644
--- a/cmd/errors.go
+++ b/cmd/errors.go
@@ -15,7 +15,7 @@ import (
 
 	"github.com/GrayCodeAI/eyrie/credentials"
 	hawkconfig "github.com/GrayCodeAI/hawk/internal/config"
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // ─── friendlyError ────────────────────────────────────────────────────────────
@@ -180,13 +180,13 @@ func friendlyError(err error) string {
 	// ── Disk full ─────────────────────────────────────────────────────────
 	if strings.Contains(low, "no space left") || strings.Contains(low, "disk full") ||
 		strings.Contains(low, "not enough space") || strings.Contains(low, "disk quota") {
-		return "Disk is full or quota exceeded. Free up space and try again.\n  Check ~/.hawk/sessions/ for old sessions you can remove."
+		return "Disk is full or quota exceeded. Free up space and try again.\n  Check Hawk's user state sessions directory for old sessions you can remove."
 	}
 
 	// ── Invalid JSON in config/settings ───────────────────────────────────
 	if (strings.Contains(low, "json") || strings.Contains(low, "unmarshal") || strings.Contains(low, "syntax error")) &&
 		(strings.Contains(low, "settings") || strings.Contains(low, "config") || strings.Contains(low, "parse") || strings.Contains(low, "invalid character")) {
-		return "Invalid JSON in configuration. Check your settings files for syntax errors:\n  ~/.hawk/settings.json\n  .hawk/settings.json\n  Tip: use a JSON linter or 'cat ~/.hawk/settings.json | python3 -m json.tool' to find the issue."
+		return "Invalid JSON in configuration. Check your Hawk settings.json files for syntax errors.\n  Tip: use a JSON linter to find the issue."
 	}
 
 	// ── TLS / certificate errors ──────────────────────────────────────────
@@ -200,7 +200,7 @@ func friendlyError(err error) string {
 
 // ─── panicRecovery ────────────────────────────────────────────────────────────
 // Catches panics, saves the current session state, logs the stack trace to
-// ~/.hawk/crash.log, and exits with a user-friendly message.
+// Hawk's user state crash log, and exits with a user-friendly message.
 
 //lint:ignore U1000 Infrastructure wired in main.go for production builds
 func panicRecovery(saveFn func()) {
@@ -216,9 +216,8 @@ func panicRecovery(saveFn func()) {
 		}
 
 		// Log to crash file
-		home := home.Dir()
-		if home != "" {
-			crashDir := filepath.Join(home, ".hawk")
+		crashDir := storage.StateDir()
+		if crashDir != "" {
 			_ = os.MkdirAll(crashDir, 0o755)
 			crashLog := filepath.Join(crashDir, "crash.log")
 
@@ -239,7 +238,7 @@ func panicRecovery(saveFn func()) {
 		// Print user-friendly message
 		_, _ = fmt.Fprintf(os.Stderr, "\nhawk encountered an unexpected error and needs to exit.\n")
 		_, _ = fmt.Fprintf(os.Stderr, "Your session has been saved.\n")
-		_, _ = fmt.Fprintf(os.Stderr, "Details logged to ~/.hawk/crash.log\n")
+		_, _ = fmt.Fprintf(os.Stderr, "Details logged to %s\n", filepath.Join(storage.StateDir(), "crash.log"))
 		_, _ = fmt.Fprintf(os.Stderr, "Please report this at: https://github.com/GrayCodeAI/hawk/issues\n\n")
 		_, _ = fmt.Fprintf(os.Stderr, "panic: %v\n", r)
 		os.Exit(1) // os.Exit intentional: panic recovery, defer already unwound
@@ -284,7 +283,7 @@ func signalHandler(saveFn func()) {
 }
 
 // ─── errorLogger ──────────────────────────────────────────────────────────────
-// Writes errors to ~/.hawk/error.log with timestamps. Thread-safe.
+// Writes errors to Hawk's user state error log with timestamps. Thread-safe.
 
 type errorLoggerT struct {
 	mu   sync.Mutex
@@ -298,11 +297,10 @@ var errLoggerOnce sync.Once
 //lint:ignore U1000 Infrastructure used by logError
 func getErrorLogger() *errorLoggerT {
 	errLoggerOnce.Do(func() {
-		home := home.Dir()
-		if home == "" {
-			home = os.TempDir()
+		dir := storage.StateDir()
+		if dir == "" {
+			dir = os.TempDir()
 		}
-		dir := filepath.Join(home, ".hawk")
 		_ = os.MkdirAll(dir, 0o755)
 		errLogger = &errorLoggerT{
 			path: filepath.Join(dir, "error.log"),
@@ -311,7 +309,7 @@ func getErrorLogger() *errorLoggerT {
 	return errLogger
 }
 
-// LogError writes a timestamped error entry to ~/.hawk/error.log.
+// LogError writes a timestamped error entry to the Hawk error log.
 func (l *errorLoggerT) LogError(context string, err error) {
 	if l == nil || err == nil {
 		return
@@ -335,7 +333,7 @@ func (l *errorLoggerT) LogError(context string, err error) {
 	_, _ = f.WriteString(entry)
 }
 
-// LogErrorf writes a formatted, timestamped error entry to ~/.hawk/error.log.
+// LogErrorf writes a formatted, timestamped error entry to the Hawk error log.
 func (l *errorLoggerT) LogErrorf(format string, args ...interface{}) {
 	if l == nil {
 		return
@@ -403,30 +401,22 @@ func validateStartup(settings hawkconfig.Settings) []StartupWarning {
 	}
 
 	// 3. Check sessions directory is writable
-	home, err := os.UserHomeDir()
-	if err != nil {
+	sessDir := storage.SessionsDir()
+	if err := os.MkdirAll(sessDir, 0o755); err != nil {
 		warnings = append(warnings, StartupWarning{
 			Check:   "sessions_dir",
-			Message: "Cannot determine home directory. Session persistence may not work.",
+			Message: fmt.Sprintf("Cannot create sessions directory %s: %v", sessDir, err),
 		})
 	} else {
-		sessDir := filepath.Join(home, ".hawk", "sessions")
-		if err := os.MkdirAll(sessDir, 0o755); err != nil {
+		// Try writing a temp file to verify writability
+		tmpPath := filepath.Join(sessDir, ".write_test")
+		if err := os.WriteFile(tmpPath, []byte("ok"), 0o644); err != nil {
 			warnings = append(warnings, StartupWarning{
 				Check:   "sessions_dir",
-				Message: fmt.Sprintf("Cannot create sessions directory %s: %v", sessDir, err),
+				Message: fmt.Sprintf("Sessions directory %s is not writable: %v", sessDir, err),
 			})
 		} else {
-			// Try writing a temp file to verify writability
-			tmpPath := filepath.Join(sessDir, ".write_test")
-			if err := os.WriteFile(tmpPath, []byte("ok"), 0o644); err != nil {
-				warnings = append(warnings, StartupWarning{
-					Check:   "sessions_dir",
-					Message: fmt.Sprintf("Sessions directory %s is not writable: %v", sessDir, err),
-				})
-			} else {
-				_ = os.Remove(tmpPath)
-			}
+			_ = os.Remove(tmpPath)
 		}
 	}
 
diff --git a/cmd/exec.go b/cmd/exec.go
index fbfedbed..5947c246 100644
--- a/cmd/exec.go
+++ b/cmd/exec.go
@@ -102,7 +102,7 @@ func init() {
 	execCmd.Flags().StringVarP(&execModel, "model", "m", "", "Model ID to use")
 	execCmd.Flags().IntVar(&execMaxTurns, "max-turns", 0, "Maximum agentic turns (0 = unlimited)")
 	execCmd.Flags().StringVar(&execCWD, "cwd", "", "Working directory")
-	execCmd.Flags().StringVar(&execAgent, "agent", "", "Agent persona to use (from ~/.hawk/agents/)")
+	execCmd.Flags().StringVar(&execAgent, "agent", "", "Agent persona to use (from Hawk user state)")
 	execCmd.Flags().StringVarP(&execSessionID, "session-id", "s", "", "Continue an existing session")
 	execCmd.Flags().StringVar(&execTag, "tag", "", "Session tag for categorization")
 	execCmd.Flags().BoolVarP(&execWorktree, "worktree", "w", false, "Run in an isolated git worktree")
@@ -508,8 +508,7 @@ type skillRunner interface {
 	Run(name string) (string, error)
 }
 
-// pluginSkillRunner is the production skillRunner backed by hawk's local skill
-// store (.hawk/skills, ~/.hawk/skills, ...).
+// pluginSkillRunner is the production skillRunner backed by Hawk skill storage.
 type pluginSkillRunner struct{}
 
 func (pluginSkillRunner) Run(name string) (string, error) {
diff --git a/cmd/exec_test.go b/cmd/exec_test.go
index d13be54f..87290318 100644
--- a/cmd/exec_test.go
+++ b/cmd/exec_test.go
@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // --- Skill dispatch tests ---------------------------------------------------
@@ -216,15 +218,12 @@ func TestResolveExecPrompt_Empty(t *testing.T) {
 func TestPersistExecSession(t *testing.T) {
 	// Set up temp session dir
 	dir := t.TempDir()
-	origHome := os.Getenv("HOME")
-	os.Setenv("HOME", dir)
-	defer os.Setenv("HOME", origHome)
-	os.MkdirAll(filepath.Join(dir, ".hawk", "sessions"), 0o755)
+	t.Setenv("HAWK_STATE_DIR", filepath.Join(dir, "state"))
 
 	persistExecSession("test-123", "claude-opus", "anthropic", "hello", "world")
 
 	// Check file exists
-	path := filepath.Join(dir, ".hawk", "sessions", "test-123.jsonl")
+	path := filepath.Join(storage.SessionsDir(), "test-123.jsonl")
 	if _, err := os.Stat(path); err != nil {
 		t.Fatalf("session file not created: %v", err)
 	}
diff --git a/cmd/feedback.go b/cmd/feedback.go
index 82819b72..04937dd7 100644
--- a/cmd/feedback.go
+++ b/cmd/feedback.go
@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/spf13/cobra"
 )
 
@@ -38,7 +39,7 @@ var feedbackCmd = &cobra.Command{
 	Short: "Submit feedback about hawk",
 	Long: `Capture feedback about your hawk experience. By default, opens a
 GitHub issue template URL in your browser. Use --local to save feedback
-to ~/.hawk/feedback/ for later submission.
+to Hawk's user state directory for later submission.
 
 Categories: bug, feature, ux, performance, other
 
@@ -89,12 +90,7 @@ func runFeedback(_ *cobra.Command, args []string) error {
 }
 
 func saveFeedbackLocal(report FeedbackReport) error {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return fmt.Errorf("get home directory: %w", err)
-	}
-
-	dir := filepath.Join(home, ".hawk", "feedback")
+	dir := filepath.Join(storage.StateDir(), "feedback")
 	if mkErr := os.MkdirAll(dir, 0o755); mkErr != nil {
 		return fmt.Errorf("create feedback directory: %w", mkErr)
 	}
diff --git a/cmd/history.go b/cmd/history.go
index e1be6405..b2988211 100644
--- a/cmd/history.go
+++ b/cmd/history.go
@@ -5,18 +5,17 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 const maxHistoryEntries = 1000
 
 // historyFilePath returns the path to the persistent input history file.
 func historyFilePath() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "history")
+	return filepath.Join(storage.StateDir(), "history")
 }
 
-// loadInputHistory loads input history from ~/.hawk/history.
+// loadInputHistory loads input history from Hawk's user state directory.
 // Returns an empty slice if the file does not exist.
 func loadInputHistory() []string {
 	data, err := os.ReadFile(historyFilePath())
@@ -34,7 +33,7 @@ func loadInputHistory() []string {
 	return entries
 }
 
-// saveInputHistory writes the history list to ~/.hawk/history.
+// saveInputHistory writes the history list to Hawk's user state directory.
 // Deduplicates entries (keeping the last occurrence) and caps at maxHistoryEntries.
 func saveInputHistory(history []string) {
 	// Deduplicate: keep the last occurrence of each entry
diff --git a/cmd/history_test.go b/cmd/history_test.go
index ab815286..dca54ac4 100644
--- a/cmd/history_test.go
+++ b/cmd/history_test.go
@@ -1,7 +1,6 @@
 package cmd
 
 import (
-	"os"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -97,8 +96,9 @@ func TestAppendToHistory_EmptySkipped(t *testing.T) {
 }
 
 func TestHistoryFilePath(t *testing.T) {
-	home, _ := os.UserHomeDir()
-	expected := filepath.Join(home, ".hawk", "history")
+	stateDir := filepath.Join(t.TempDir(), "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
+	expected := filepath.Join(stateDir, "history")
 	if got := historyFilePath(); got != expected {
 		t.Fatalf("got %q, want %q", got, expected)
 	}
diff --git a/cmd/manpage.go b/cmd/manpage.go
index a90d100d..3484f833 100644
--- a/cmd/manpage.go
+++ b/cmd/manpage.go
@@ -83,11 +83,9 @@ func GenerateManPage() string {
 
 	// Files
 	b.WriteString(".SH FILES\n")
-	b.WriteString(".TP\n\\fB~/.hawk/settings.json\\fR\nGlobal configuration file\n")
-	b.WriteString(".TP\n\\fB.hawk/settings.json\\fR\nProject-level configuration\n")
-	b.WriteString(".TP\n\\fBAGENTS.md\\fR\nProject instructions file (also reads AGENTS.md for backward compatibility)\n")
-	b.WriteString(".TP\n\\fB~/.hawk/sessions/\\fR\nSaved session data\n")
-	b.WriteString(".TP\n\\fB~/.hawk/templates/\\fR\nPrompt templates\n")
+	b.WriteString(".TP\n\\fBHawk user config directory\\fR\nGlobal configuration files\n")
+	b.WriteString(".TP\n\\fBAGENTS.md\\fR\nProject instructions file\n")
+	b.WriteString(".TP\n\\fBHawk user state directory\\fR\nSaved session data, plans, skills, and runtime state\n")
 
 	// Credentials (stored in OS secret service — use /config, not .env)
 	b.WriteString(".SH CREDENTIALS\n")
diff --git a/cmd/permissions_center.go b/cmd/permissions_center.go
index 64092236..ae51df0a 100644
--- a/cmd/permissions_center.go
+++ b/cmd/permissions_center.go
@@ -259,7 +259,7 @@ func rebuildSessionPermissionRules(sess *engine.Session, settings hawkconfig.Set
 func savePermissionSettings(scope string, settings hawkconfig.Settings, level engine.AutonomyLevel) (string, error) {
 	scope = strings.ToLower(strings.TrimSpace(scope))
 	if scope == "" {
-		scope = "project"
+		scope = "global"
 	}
 	settings.Autonomy = permissionTierSettingValue(level)
 	settings.Sandbox = effectivePermissionSandbox(settings)
@@ -268,16 +268,7 @@ func savePermissionSettings(scope string, settings hawkconfig.Settings, level en
 
 	switch scope {
 	case "project":
-		target := hawkconfig.LoadProjectSettings()
-		target.AutoAllow = append([]string{}, settings.AutoAllow...)
-		target.AllowedTools = append([]string{}, settings.AllowedTools...)
-		target.DisallowedTools = append([]string{}, settings.DisallowedTools...)
-		target.Autonomy = settings.Autonomy
-		target.Sandbox = settings.Sandbox
-		if err := hawkconfig.SaveProject(target); err != nil {
-			return "", err
-		}
-		return ".hawk/settings.json", nil
+		return "", fmt.Errorf("project-local settings writes are disabled; use scope \"global\" or an explicit --settings file")
 	case "global":
 		target := hawkconfig.LoadGlobalSettings()
 		target.AutoAllow = append([]string{}, settings.AutoAllow...)
@@ -288,7 +279,7 @@ func savePermissionSettings(scope string, settings hawkconfig.Settings, level en
 		if err := hawkconfig.SaveGlobal(target); err != nil {
 			return "", err
 		}
-		return "~/.hawk/settings.json", nil
+		return "user settings", nil
 	default:
 		return "", fmt.Errorf("valid save scopes: project, global")
 	}
diff --git a/cmd/plan.go b/cmd/plan.go
index e43fc79d..ac72d41f 100644
--- a/cmd/plan.go
+++ b/cmd/plan.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 
 	"github.com/GrayCodeAI/hawk/internal/intelligence/planner"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/spf13/cobra"
 )
 
@@ -16,7 +17,7 @@ var planCmd = &cobra.Command{
 	Use:   "plan",
 	Short: "Create and manage structured development plans",
 	Long: `plan helps you create, list, and track structured development plans.
-Plans are stored as JSON files in .hawk/plans/.
+Plans are stored in Hawk's user state directory, partitioned by project.
 
 Subcommands:
   create <description>   Create a new plan (generates a plan prompt)
@@ -41,7 +42,7 @@ var planCreateCmd = &cobra.Command{
 		cmd.Println("--- User ---")
 		cmd.Println(prompt.User)
 		cmd.Println()
-		cmd.Println("Once you have the LLM response, save it as a JSON file in .hawk/plans/.")
+		cmd.Println("Once you have the LLM response, save it with an explicit output path or import it into Hawk plans.")
 		return nil
 	},
 }
@@ -50,7 +51,7 @@ var planListCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List all saved plans",
 	RunE: func(cmd *cobra.Command, args []string) error {
-		plansDir := filepath.Join(".", ".hawk", "plans")
+		plansDir := currentProjectPlansDir()
 		entries, err := os.ReadDir(plansDir)
 		if err != nil {
 			if os.IsNotExist(err) {
@@ -115,7 +116,7 @@ var planDoneCmd = &cobra.Command{
 	Use:   "done <task-id>",
 	Short: "Mark a task as completed in the most recent plan",
 	Long: `Mark a task as done by its numeric ID. This operates on the most
-recently modified plan in .hawk/plans/.
+recently modified plan in Hawk's user state directory for the current project.
 
 To target a specific plan, set the plan name as the first argument
 followed by the task ID: hawk plan done <name> <task-id>`,
@@ -170,18 +171,19 @@ func init() {
 	planCmd.AddCommand(planDoneCmd)
 }
 
-// resolvePlanPath converts a plan name to a file path in .hawk/plans/.
+// resolvePlanPath converts a plan name to a file path in Hawk's user state dir.
 func resolvePlanPath(name string) string {
+	plansDir := currentProjectPlansDir()
 	// If the name already has a .json extension, use it directly.
 	if strings.HasSuffix(name, ".json") {
-		return filepath.Join(".", ".hawk", "plans", name)
+		return filepath.Join(plansDir, name)
 	}
-	return filepath.Join(".", ".hawk", "plans", name+".json")
+	return filepath.Join(plansDir, name+".json")
 }
 
 // mostRecentPlan returns the path to the most recently modified plan.
 func mostRecentPlan() (string, error) {
-	plansDir := filepath.Join(".", ".hawk", "plans")
+	plansDir := currentProjectPlansDir()
 	entries, err := os.ReadDir(plansDir)
 	if err != nil {
 		return "", fmt.Errorf("no plans directory found: %w", err)
@@ -205,7 +207,15 @@ func mostRecentPlan() (string, error) {
 	}
 
 	if newest == "" {
-		return "", fmt.Errorf("no plans found in .hawk/plans/")
+		return "", fmt.Errorf("no plans found")
 	}
 	return newest, nil
 }
+
+func currentProjectPlansDir() string {
+	cwd, err := os.Getwd()
+	if err != nil {
+		cwd = "."
+	}
+	return storage.PlansDir(cwd)
+}
diff --git a/cmd/review.go b/cmd/review.go
index 3bf61d8d..cdc2633e 100644
--- a/cmd/review.go
+++ b/cmd/review.go
@@ -71,10 +71,6 @@ func runReviewInit(_ *cobra.Command, _ []string) error {
 		return fmt.Errorf("write hook: %w", err)
 	}
 
-	// Ensure .hawk directory exists for the review DB.
-	projectDir, _ := os.Getwd()
-	_ = os.MkdirAll(filepath.Join(projectDir, ".hawk"), 0o755)
-
 	fmt.Printf("%s Installed post-commit hook at %s\n", icons.CheckBold(), hookPath)
 	fmt.Println("  Every commit will now be reviewed automatically.")
 	fmt.Println("  View reviews: hawk review status")
diff --git a/cmd/review_store.go b/cmd/review_store.go
index 77f2d2ea..153b7174 100644
--- a/cmd/review_store.go
+++ b/cmd/review_store.go
@@ -4,11 +4,13 @@ import (
 	"database/sql"
 	"encoding/json"
 	"fmt"
+	"os"
 	"path/filepath"
 	"strings"
 	"sync"
 	"time"
 
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	sightLib "github.com/GrayCodeAI/sight"
 )
 
@@ -64,7 +66,11 @@ type ReviewStore struct {
 
 // OpenReviewStore opens or creates the review database.
 func OpenReviewStore(projectDir string) (*ReviewStore, error) {
-	dbPath := filepath.Join(projectDir, ".hawk", "reviews.db")
+	dbDir := storage.ProjectStateDir(projectDir)
+	if err := os.MkdirAll(dbDir, 0o755); err != nil {
+		return nil, fmt.Errorf("create review db directory: %w", err)
+	}
+	dbPath := filepath.Join(dbDir, "reviews.db")
 	db, err := sql.Open("sqlite", dbPath)
 	if err != nil {
 		return nil, fmt.Errorf("open review db: %w", err)
diff --git a/cmd/root.go b/cmd/root.go
index e872f90e..45ff1d99 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -63,7 +63,6 @@ var (
 	containerMode              bool
 	noContainer                bool
 	recoverFlag                bool
-	allowProjectMCP            bool
 	startupProfileFlag         bool
 )
 
@@ -148,7 +147,7 @@ var rootCmd = &cobra.Command{
 
 		// Extract bundled skills on first run.
 		if n, _ := plugin.ExtractBundledSkills(); n > 0 {
-			fmt.Printf("Extracted %d bundled skills to ~/.hawk/bundled-skills/\n", n)
+			fmt.Printf("Extracted %d bundled skills to Hawk user state\n", n)
 		}
 
 		// Recovery: scan for interrupted sessions before launching TUI.
@@ -216,7 +215,6 @@ func init() {
 	rootCmd.Flags().BoolVar(&refreshCatalogFlag, "refresh-catalog", false, "refresh the eyrie model catalog before starting")
 	rootCmd.Flags().BoolVar(&skipCatalogRefreshFlag, "no-auto-catalog-refresh", false, "disable automatic catalog refresh when cache is missing, empty, or stale")
 	rootCmd.Flags().BoolVar(&recoverFlag, "recover", false, "scan for interrupted sessions and offer to resume")
-	rootCmd.Flags().BoolVar(&allowProjectMCP, "allow-project-mcp", false, "allow MCP servers defined in project-level .hawk/settings.json (security risk)")
 	rootCmd.Flags().BoolVar(&startupProfileFlag, "startup-profile", false, "print startup performance profile")
 	rootCmd.AddCommand(versionCmd)
 	rootCmd.AddCommand(setupCmd)
diff --git a/cmd/rules.go b/cmd/rules.go
index b52434b6..4ce90267 100644
--- a/cmd/rules.go
+++ b/cmd/rules.go
@@ -67,7 +67,7 @@ var rulesImportCmd = &cobra.Command{
 			return fmt.Errorf("export to hawk format failed: %w", err)
 		}
 
-		cmd.Println(fmt.Sprintf("Imported %d rule(s) from %s to .hawk/rules/.", len(imported), rulesImportFrom))
+		cmd.Println(fmt.Sprintf("Imported %d rule(s) from %s to .agents/rules/.", len(imported), rulesImportFrom))
 		for _, r := range imported {
 			cmd.Println(fmt.Sprintf("  - %s", r.Name))
 		}
@@ -90,7 +90,7 @@ var rulesExportCmd = &cobra.Command{
 		}
 
 		if len(hawkRules) == 0 {
-			cmd.Println("No hawk rules found in .hawk/rules/. Nothing to export.")
+			cmd.Println("No hawk rules found in .agents/rules/. Nothing to export.")
 			return nil
 		}
 
diff --git a/cmd/storage_policy_test.go b/cmd/storage_policy_test.go
new file mode 100644
index 00000000..20025a6d
--- /dev/null
+++ b/cmd/storage_policy_test.go
@@ -0,0 +1,33 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestStoragePolicyHelpersDoNotCreateProjectHawk(t *testing.T) {
+	project := t.TempDir()
+	t.Setenv("HAWK_STATE_DIR", filepath.Join(t.TempDir(), "state"))
+	t.Setenv("HAWK_CACHE_DIR", filepath.Join(t.TempDir(), "cache"))
+	oldwd, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = os.Chdir(oldwd) })
+	if err := os.Chdir(project); err != nil {
+		t.Fatal(err)
+	}
+
+	planPath := resolvePlanPath("demo")
+	if strings.Contains(planPath, filepath.Join(project, ".hawk")) {
+		t.Fatalf("resolvePlanPath leaked project .hawk: %q", planPath)
+	}
+	saveInputHistory([]string{"hello"})
+	recordTipShown("slash-help")
+
+	if _, err := os.Stat(filepath.Join(project, ".hawk")); !os.IsNotExist(err) {
+		t.Fatalf("normal storage helpers created project .hawk, stat err=%v", err)
+	}
+}
diff --git a/cmd/tips.go b/cmd/tips.go
index 18c4eae1..b3744fe8 100644
--- a/cmd/tips.go
+++ b/cmd/tips.go
@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Tip represents a single hawk usage tip.
@@ -51,8 +51,7 @@ func allTips() []Tip {
 
 // tipHistoryPath returns the path to the tip history file.
 func tipHistoryPath() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "tip_history.json")
+	return filepath.Join(storage.StateDir(), "tip_history.json")
 }
 
 // tipHistory represents recently shown tip IDs with timestamps.
@@ -74,8 +73,7 @@ func loadTipHistory() tipHistory {
 }
 
 func saveTipHistory(h tipHistory) {
-	home := home.Dir()
-	_ = os.MkdirAll(filepath.Join(home, ".hawk"), 0o755)
+	_ = os.MkdirAll(storage.StateDir(), 0o755)
 	data, _ := json.MarshalIndent(h, "", "  ")
 	_ = os.WriteFile(tipHistoryPath(), data, 0o644)
 }
diff --git a/external/eyrie b/external/eyrie
index abeb7277..a3547d9e 160000
--- a/external/eyrie
+++ b/external/eyrie
@@ -1 +1 @@
-Subproject commit abeb7277e5cfb754b654a1dbbb72bc7e9e958109
+Subproject commit a3547d9e481002564f0e253c3ded56c21877c4d0
diff --git a/internal/auth/auth.go b/internal/auth/auth.go
index 509ea84e..9713ce98 100644
--- a/internal/auth/auth.go
+++ b/internal/auth/auth.go
@@ -11,6 +11,8 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // TokenStore manages authentication tokens.
@@ -93,19 +95,8 @@ func (s *SecureStorage) setMacOS(account, token string) error {
 	return err
 }
 
-func homeDir() string {
-	if runtime.GOOS == "windows" {
-		if d := os.Getenv("USERPROFILE"); d != "" {
-			return d
-		}
-		return os.Getenv("HOMEDRIVE") + os.Getenv("HOMEPATH")
-	}
-	home, _ := os.UserHomeDir()
-	return home
-}
-
 func (s *SecureStorage) getFile(account string) (string, error) {
-	path := filepath.Join(homeDir(), ".hawk", ".tokens")
+	path := filepath.Join(storage.ConfigDir(), ".tokens")
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return "", err
@@ -118,7 +109,10 @@ func (s *SecureStorage) getFile(account string) (string, error) {
 }
 
 func (s *SecureStorage) setFile(account, token string) error {
-	path := filepath.Join(homeDir(), ".hawk", ".tokens")
+	path := filepath.Join(storage.ConfigDir(), ".tokens")
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return err
+	}
 	var tokens map[string]string
 	if data, err := os.ReadFile(path); err == nil {
 		_ = json.Unmarshal(data, &tokens)
diff --git a/internal/auth/auth_test.go b/internal/auth/auth_test.go
index de3d5876..e4a6b4cc 100644
--- a/internal/auth/auth_test.go
+++ b/internal/auth/auth_test.go
@@ -5,6 +5,8 @@ import (
 	"os"
 	"path/filepath"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 func TestTokenStore(t *testing.T) {
@@ -152,11 +154,6 @@ func TestSecureStorage(t *testing.T) {
 		dir := t.TempDir()
 		t.Setenv("HOME", dir)
 
-		hawkDir := filepath.Join(dir, ".hawk")
-		if err := os.MkdirAll(hawkDir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-
 		ss := NewSecureStorage("hawk-test")
 		if err := ss.setFile("anthropic", "sk-test-token"); err != nil {
 			t.Fatalf("setFile() error = %v", err)
@@ -175,11 +172,6 @@ func TestSecureStorage(t *testing.T) {
 		dir := t.TempDir()
 		t.Setenv("HOME", dir)
 
-		hawkDir := filepath.Join(dir, ".hawk")
-		if err := os.MkdirAll(hawkDir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-
 		ss := NewSecureStorage("hawk-test")
 		if err := ss.setFile("provider", "old-token"); err != nil {
 			t.Fatal(err)
@@ -201,17 +193,12 @@ func TestSecureStorage(t *testing.T) {
 		dir := t.TempDir()
 		t.Setenv("HOME", dir)
 
-		hawkDir := filepath.Join(dir, ".hawk")
-		if err := os.MkdirAll(hawkDir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-
 		ss := NewSecureStorage("hawk-test")
 		if err := ss.setFile("test", "secret"); err != nil {
 			t.Fatal(err)
 		}
 
-		path := filepath.Join(hawkDir, ".tokens")
+		path := filepath.Join(storage.ConfigDir(), ".tokens")
 		info, err := os.Stat(path)
 		if err != nil {
 			t.Fatal(err)
@@ -226,11 +213,6 @@ func TestSecureStorage(t *testing.T) {
 		dir := t.TempDir()
 		t.Setenv("HOME", dir)
 
-		hawkDir := filepath.Join(dir, ".hawk")
-		if err := os.MkdirAll(hawkDir, 0o755); err != nil {
-			t.Fatal(err)
-		}
-
 		ss := NewSecureStorage("hawk-test")
 		if err := ss.setFile("provider1", "token1"); err != nil {
 			t.Fatal(err)
@@ -239,7 +221,7 @@ func TestSecureStorage(t *testing.T) {
 			t.Fatal(err)
 		}
 
-		data, err := os.ReadFile(filepath.Join(hawkDir, ".tokens"))
+		data, err := os.ReadFile(filepath.Join(storage.ConfigDir(), ".tokens"))
 		if err != nil {
 			t.Fatal(err)
 		}
diff --git a/internal/autoinit/autoinit.go b/internal/autoinit/autoinit.go
index 80f890c4..9f4a8e5a 100644
--- a/internal/autoinit/autoinit.go
+++ b/internal/autoinit/autoinit.go
@@ -19,9 +19,10 @@ import (
 	"strings"
 
 	"github.com/GrayCodeAI/hawk/internal/config"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
-// markerName is the file written under the project's .hawk directory once an
+// markerName is the file written under the project's user-state directory once an
 // auto-init run has been attempted. Its presence (regardless of run outcome)
 // prevents repeated attempts on subsequent invocations.
 const markerName = "auto-init.done"
@@ -81,7 +82,7 @@ func HasContext(root string) bool {
 
 // MarkerPath returns the path to the auto-init marker file for root.
 func MarkerPath(root string) string {
-	return filepath.Join(root, ".hawk", markerName)
+	return filepath.Join(storage.ProjectStateDir(root), markerName)
 }
 
 // HasRun reports whether auto-init has already been attempted for root.
@@ -139,7 +140,7 @@ func MaybeRun(ctx context.Context, opts Options) (Decision, error) {
 }
 
 func writeMarker(root string) error {
-	dir := filepath.Join(root, ".hawk")
+	dir := storage.ProjectStateDir(root)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return err
 	}
diff --git a/internal/config/config.go b/internal/config/config.go
index 1ebd9fdc..80d7c68f 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -12,7 +12,7 @@ import (
 	"github.com/GrayCodeAI/hawk/internal/intelligence/memory"
 )
 
-// LoadAgentsMD reads AGENTS.md (or AGENTS.md for backward compatibility) from the current directory or parents.
+// LoadAgentsMD reads AGENTS.md from the current directory or parents.
 func LoadAgentsMD() string {
 	dir, _ := os.Getwd()
 	return LoadAgentsMDFrom(dir)
@@ -21,12 +21,11 @@ func LoadAgentsMD() string {
 const maxAgentsMDSize = 10 * 1024 // 10KB
 
 // agentFiles lists project instruction filenames in priority order.
-// AGENTS.md is the canonical name; AGENTS.md is kept for backward compatibility.
 var agentFiles = []string{
-	"AGENTS.md", ".hawk/AGENTS.md", ".agent/AGENTS.md",
+	"AGENTS.md",
 }
 
-// LoadAgentsMDFrom reads AGENTS.md (or AGENTS.md fallback) from start or its parents.
+// LoadAgentsMDFrom reads AGENTS.md from start or its parents.
 func LoadAgentsMDFrom(start string) string {
 	dir := start
 	if dir == "" {
@@ -54,18 +53,15 @@ func LoadAgentsMDFrom(start string) string {
 	return ""
 }
 
-// LoadAgentDir returns the path to .hawk/ or .agent/ directory, whichever exists.
-// .hawk/ takes priority. Returns empty string if neither exists.
+// LoadAgentDir returns the path to .agent/ if it exists.
 func LoadAgentDir() string {
 	dir, _ := os.Getwd()
 	if abs, err := filepath.Abs(dir); err == nil {
 		dir = abs
 	}
-	for _, name := range []string{".hawk", ".agent"} {
-		p := filepath.Join(dir, name)
-		if info, err := os.Stat(p); err == nil && info.IsDir() {
-			return p
-		}
+	p := filepath.Join(dir, ".agent")
+	if info, err := os.Stat(p); err == nil && info.IsDir() {
+		return p
 	}
 	return ""
 }
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index a2b9f824..98ba9722 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -112,32 +112,21 @@ func TestLoadSettingsAcceptsArchiveCamelCase(t *testing.T) {
 	}
 }
 
-func TestLoadSettingsProjectMergeIncludesArchiveFields(t *testing.T) {
+func TestLoadSettingsUsesUserConfigOnly(t *testing.T) {
 	home := t.TempDir()
-	project := t.TempDir()
 	t.Setenv("HOME", home)
-	if err := os.MkdirAll(filepath.Join(home, ".hawk"), 0o755); err != nil {
+	configDir := filepath.Join(home, "config")
+	t.Setenv("HAWK_CONFIG_DIR", configDir)
+	if err := os.MkdirAll(configDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.WriteFile(filepath.Join(home, ".hawk", "settings.json"), []byte(`{"model":"global","allowedTools":["Read"]}`), 0o644); err != nil {
+	if err := os.WriteFile(filepath.Join(configDir, "settings.json"), []byte(`{"model":"global","allowedTools":["Read"]}`), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	if err := os.MkdirAll(filepath.Join(project, ".hawk"), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(filepath.Join(project, ".hawk", "settings.json"), []byte(`{"model":"project","disallowedTools":["Write"],"mcpServers":[{"name":"demo","command":"demo-mcp"}]}`), 0o644); err != nil {
-		t.Fatal(err)
-	}
-
-	orig, _ := os.Getwd()
-	if err := os.Chdir(project); err != nil {
-		t.Fatal(err)
-	}
-	defer os.Chdir(orig)
 
 	settings := LoadSettings()
-	if got := ActiveModel(context.TODO()); got != "project" {
-		t.Fatalf("expected project model in eyrie, got %q (settings.model=%q)", got, settings.Model)
+	if got := ActiveModel(context.TODO()); got != "global" {
+		t.Fatalf("expected global model in eyrie, got %q (settings.model=%q)", got, settings.Model)
 	}
 	if settings.Model != "" {
 		t.Fatalf("model must not remain in hawk settings.json, got %q", settings.Model)
@@ -145,11 +134,11 @@ func TestLoadSettingsProjectMergeIncludesArchiveFields(t *testing.T) {
 	if len(settings.AllowedTools) != 1 || settings.AllowedTools[0] != "Read" {
 		t.Fatalf("expected global allowedTools, got %v", settings.AllowedTools)
 	}
-	if len(settings.DisallowedTools) != 1 || settings.DisallowedTools[0] != "Write" {
-		t.Fatalf("expected project disallowedTools, got %v", settings.DisallowedTools)
+	if len(settings.DisallowedTools) != 0 {
+		t.Fatalf("unexpected disallowedTools, got %v", settings.DisallowedTools)
 	}
-	if len(settings.MCPServers) != 1 || settings.MCPServers[0].Name != "demo" {
-		t.Fatalf("expected project mcpServers, got %v", settings.MCPServers)
+	if len(settings.MCPServers) != 0 {
+		t.Fatalf("unexpected mcpServers, got %v", settings.MCPServers)
 	}
 }
 
@@ -195,41 +184,13 @@ func TestSetGlobalSettingAndSettingValue(t *testing.T) {
 	}
 }
 
-func TestLoadAgentsMD_AgentDir(t *testing.T) {
-	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".agent"), 0o755)
-	os.WriteFile(filepath.Join(dir, ".agent", "AGENTS.md"), []byte("agent dir instructions"), 0o644)
-
-	md := LoadAgentsMDFrom(dir)
-	if md != "agent dir instructions" {
-		t.Fatalf("expected .agent/AGENTS.md content, got %q", md)
-	}
-}
-
-func TestLoadAgentsMD_HawkDirPriority(t *testing.T) {
+func TestLoadAgentsMD_VisibleFile(t *testing.T) {
 	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755)
-	os.WriteFile(filepath.Join(dir, ".hawk", "AGENTS.md"), []byte("hawk dir"), 0o644)
-	os.MkdirAll(filepath.Join(dir, ".agent"), 0o755)
-	os.WriteFile(filepath.Join(dir, ".agent", "AGENTS.md"), []byte("agent dir"), 0o644)
+	os.WriteFile(filepath.Join(dir, "AGENTS.md"), []byte("project instructions"), 0o644)
 
 	md := LoadAgentsMDFrom(dir)
-	if md != "hawk dir" {
-		t.Fatalf("expected .hawk/ to take priority, got %q", md)
-	}
-}
-
-func TestLoadAgentDir_Hawk(t *testing.T) {
-	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755)
-
-	orig, _ := os.Getwd()
-	os.Chdir(dir)
-	defer os.Chdir(orig)
-
-	got := LoadAgentDir()
-	if !strings.HasSuffix(got, ".hawk") || got == "" {
-		t.Fatalf("expected path ending in .hawk, got %q", got)
+	if md != "project instructions" {
+		t.Fatalf("expected AGENTS.md content, got %q", md)
 	}
 }
 
@@ -259,18 +220,3 @@ func TestLoadAgentDir_Neither(t *testing.T) {
 		t.Fatalf("expected empty, got %q", got)
 	}
 }
-
-func TestLoadAgentDir_HawkPriority(t *testing.T) {
-	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755)
-	os.MkdirAll(filepath.Join(dir, ".agent"), 0o755)
-
-	orig, _ := os.Getwd()
-	os.Chdir(dir)
-	defer os.Chdir(orig)
-
-	got := LoadAgentDir()
-	if !strings.HasSuffix(got, ".hawk") || got == "" {
-		t.Fatalf("expected .hawk priority, got %q", got)
-	}
-}
diff --git a/internal/config/credentials_store.go b/internal/config/credentials_store.go
index a63fa33c..34127a2f 100644
--- a/internal/config/credentials_store.go
+++ b/internal/config/credentials_store.go
@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"strings"
-	"sync"
 
 	eyriecfg "github.com/GrayCodeAI/eyrie/config"
 	"github.com/GrayCodeAI/eyrie/credentials"
@@ -12,8 +11,6 @@ import (
 	"github.com/GrayCodeAI/eyrie/setup"
 )
 
-var credentialDiscoveryPrepared sync.Once
-
 // PersistAPIKey saves a provider API key via eyrie (OS secret store).
 func PersistAPIKey(ctx context.Context, envKey, secret string) error {
 	secret = strings.TrimSpace(secret)
@@ -31,14 +28,11 @@ func PersistAPIKey(ctx context.Context, envKey, secret string) error {
 	return nil
 }
 
-// PrepareCredentialDiscovery migrates any legacy ~/.hawk/env keys into the OS secret store (once per process).
+// PrepareCredentialDiscovery prepares runtime credential discovery without reading legacy files.
 func PrepareCredentialDiscovery(ctx context.Context) {
 	if ctx == nil {
 		ctx = context.Background()
 	}
-	credentialDiscoveryPrepared.Do(func() {
-		_, _ = credentials.MigrateLegacyEnvFile(ctx)
-	})
 	ApplyXiaomiTokenPlanRegionEnv(ctx)
 }
 
diff --git a/internal/config/deployments_ui.go b/internal/config/deployments_ui.go
index 24a61852..524e4172 100644
--- a/internal/config/deployments_ui.go
+++ b/internal/config/deployments_ui.go
@@ -1,11 +1,5 @@
 package config
 
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-)
-
 // DeploymentRoutingLabel returns a short on/off label for the config hub.
 func DeploymentRoutingLabel(settings Settings) string {
 	if DeploymentRoutingEnabled(settings) {
@@ -14,25 +8,8 @@ func DeploymentRoutingLabel(settings Settings) string {
 	return "off"
 }
 
-// SaveProjectOrGlobalDeploymentRouting persists the flag to project settings when present.
+// SaveProjectOrGlobalDeploymentRouting persists the flag to user settings.
 func SaveProjectOrGlobalDeploymentRouting(enabled bool) error {
-	projectPath := projectSettingsPath()
-	if _, err := os.Stat(projectPath); err == nil {
-		var s Settings
-		data, err := os.ReadFile(projectPath)
-		if err != nil {
-			return err
-		}
-		if json.Unmarshal(data, &s) != nil {
-			return fmt.Errorf("parse project settings")
-		}
-		s.DeploymentRouting = &enabled
-		out, err := json.MarshalIndent(s, "", "  ")
-		if err != nil {
-			return err
-		}
-		return os.WriteFile(projectPath, append(out, '\n'), 0o644)
-	}
 	val := "false"
 	if enabled {
 		val = "true"
diff --git a/internal/config/settings.go b/internal/config/settings.go
index c9cc0108..00bbdfe4 100644
--- a/internal/config/settings.go
+++ b/internal/config/settings.go
@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/GrayCodeAI/hawk/internal/provider/routing"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 
 	"github.com/GrayCodeAI/eyrie/catalog"
 	eyriecfg "github.com/GrayCodeAI/eyrie/config"
@@ -19,7 +20,6 @@ import (
 	"github.com/GrayCodeAI/eyrie/runtime"
 	"github.com/GrayCodeAI/eyrie/setup"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/types"
 )
 
@@ -150,56 +150,23 @@ type MCPServerConfig struct {
 }
 
 func globalSettingsPath() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "settings.json")
+	return storage.SettingsPath()
 }
 
-func projectSettingsPath() string {
-	return filepath.Join(".hawk", "settings.json")
-}
-
-// LoadGlobalSettings loads only ~/.hawk/settings.json.
+// LoadGlobalSettings loads only Hawk's user config settings.json.
 func LoadGlobalSettings() Settings {
 	var s Settings
 	if data, err := os.ReadFile(globalSettingsPath()); err == nil {
 		if err := json.Unmarshal(data, &s); err != nil {
-			// Settings file exists but is malformed — log but don't crash.
 			fmt.Fprintf(os.Stderr, "hawk: warning: failed to parse %s: %v\n", globalSettingsPath(), err)
 		}
 	}
 	return s
 }
 
-// LoadProjectSettings loads only the project-level .hawk/settings.json.
-// Returns a zero-value Settings if the file does not exist.
-func LoadProjectSettings() Settings {
-	var s Settings
-	if data, err := os.ReadFile(projectSettingsPath()); err == nil {
-		if err := json.Unmarshal(data, &s); err != nil {
-			fmt.Fprintf(os.Stderr, "hawk: warning: failed to parse %s: %v\n", projectSettingsPath(), err)
-		}
-	}
-	return s
-}
-
-// ProjectMCPServers returns MCP servers defined in the project-level
-// .hawk/settings.json (not global). Returns nil if the file does not exist
-// or defines no MCP servers.
-func ProjectMCPServers() []MCPServerConfig {
-	proj := LoadProjectSettings()
-	return proj.MCPServers
-}
-
-// LoadSettings loads settings from global + project, with project overriding global.
+// LoadSettings loads settings from user config.
 func LoadSettings() Settings {
 	s := LoadGlobalSettings()
-	// Project overrides
-	var proj Settings
-	if data, err := os.ReadFile(projectSettingsPath()); err == nil {
-		if json.Unmarshal(data, &proj) == nil {
-			s = MergeSettings(s, proj)
-		}
-	}
 	migrateLegacyModelProvider(&s)
 	return s
 }
@@ -326,17 +293,6 @@ func SaveGlobal(s Settings) error {
 	return os.WriteFile(globalSettingsPath(), data, 0o644)
 }
 
-// SaveProject saves settings to the project config file.
-func SaveProject(s Settings) error {
-	s = stripHostModelSelection(s)
-	_ = os.MkdirAll(".hawk", 0o755)
-	data, err := json.MarshalIndent(s, "", "  ")
-	if err != nil {
-		return err
-	}
-	return os.WriteFile(projectSettingsPath(), data, 0o644)
-}
-
 // SettingValue returns a display-safe value for a supported setting key.
 func SettingValue(s Settings, key string) (string, bool) {
 	normalized := normalizeSettingKey(key)
@@ -400,7 +356,7 @@ func SettingValue(s Settings, key string) (string, bool) {
 	}
 }
 
-// SetGlobalSetting updates a supported scalar/list setting in ~/.hawk/settings.json.
+// SetGlobalSetting updates a supported scalar/list setting in Hawk user config.
 // Hawk: API keys are NOT stored in settings.json. Use /config and the OS secret store.
 func SetGlobalSetting(key, value string) error {
 	s := LoadGlobalSettings()
diff --git a/internal/config/xiaomi_setup_test.go b/internal/config/xiaomi_setup_test.go
index 246e042e..33cf9fb6 100644
--- a/internal/config/xiaomi_setup_test.go
+++ b/internal/config/xiaomi_setup_test.go
@@ -9,6 +9,7 @@ import (
 
 func TestSetXiaomiTokenPlanRegion_ClearsStaleBaseHost(t *testing.T) {
 	dir := t.TempDir()
+	t.Setenv("HOME", t.TempDir())
 	t.Setenv("HAWK_CONFIG_DIR", dir)
 	cfg := &eyriecfg.ProviderConfig{
 		Version:                    "2",
@@ -34,6 +35,7 @@ func TestSetXiaomiTokenPlanRegion_ClearsStaleBaseHost(t *testing.T) {
 
 func TestNeedsXiaomiTokenPlanRegion_InvalidAndMissing(t *testing.T) {
 	dir := t.TempDir()
+	t.Setenv("HOME", t.TempDir())
 	t.Setenv("HAWK_CONFIG_DIR", dir)
 
 	if !NeedsXiaomiTokenPlanRegion(ProviderXiaomiTokenPlan) {
diff --git a/internal/context/rules.go b/internal/context/rules.go
index f47fb9c8..aeeb1cf2 100644
--- a/internal/context/rules.go
+++ b/internal/context/rules.go
@@ -9,6 +9,8 @@ import (
 	"runtime"
 	"sort"
 	"strings"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // managedSource is the synthetic source name for IT-managed (org policy) rules.
@@ -39,14 +41,14 @@ func stripHTMLComments(s string) string {
 
 // RuleSource defines a source of rule files with precedence.
 type RuleSource struct {
-	Name     string // directory or file name (e.g., ".hawk/rules", "AGENTS.md")
+	Name     string // directory or file name (e.g., ".agents/rules", "AGENTS.md")
 	Priority int    // lower = higher priority
 	IsDir    bool   // true = scan directory recursively for *.md files
 }
 
 // DefaultRuleSources lists rule sources in priority order.
 var DefaultRuleSources = []RuleSource{
-	{".hawk/rules", 1, true},
+	{".agents/rules", 1, true},
 	{".omo/rules", 2, true},
 	{".claude/rules", 3, true},
 	{".cursor/rules", 4, true},
@@ -63,7 +65,7 @@ type Rule struct {
 	Path     string
 	Content  string
 	Hash     string
-	Source   string // e.g., ".hawk/rules", "AGENTS.md"
+	Source   string // e.g., ".agents/rules", "AGENTS.md"
 	Local    bool   // true if found in the file's directory tree, false if global
 	Distance int    // 0 = same directory, 1 = parent, etc.
 	Priority int    // source priority
@@ -85,7 +87,7 @@ func NewRuleDiscoverer(projectRoot string) *RuleDiscoverer {
 	var globalDirs []string
 	if home != "" {
 		globalDirs = []string{
-			filepath.Join(home, ".hawk", "rules"),
+			filepath.Join(storage.StateDir(), "rules"),
 			filepath.Join(home, ".omo", "rules"),
 			filepath.Join(home, ".claude", "rules"),
 		}
diff --git a/internal/context/rules_test.go b/internal/context/rules_test.go
index f4b77547..062fa2a7 100644
--- a/internal/context/rules_test.go
+++ b/internal/context/rules_test.go
@@ -76,7 +76,7 @@ func TestRuleDiscoverer_Deduplication(t *testing.T) {
 
 func TestRuleDiscoverer_DirectorySources(t *testing.T) {
 	dir := t.TempDir()
-	rulesDir := filepath.Join(dir, ".hawk", "rules")
+	rulesDir := filepath.Join(dir, ".agents", "rules")
 	os.MkdirAll(rulesDir, 0o755)
 	os.WriteFile(filepath.Join(rulesDir, "naming.md"), []byte("# Naming Conventions"), 0o644)
 	os.WriteFile(filepath.Join(rulesDir, "testing.md"), []byte("# Testing Rules"), 0o644)
@@ -91,12 +91,12 @@ func TestRuleDiscoverer_DirectorySources(t *testing.T) {
 
 	found := 0
 	for _, r := range rules {
-		if r.Source == ".hawk/rules" {
+		if r.Source == ".agents/rules" {
 			found++
 		}
 	}
 	if found != 2 {
-		t.Errorf("expected 2 rules from .hawk/rules, got %d", found)
+		t.Errorf("expected 2 rules from .agents/rules, got %d", found)
 	}
 }
 
@@ -133,9 +133,9 @@ func TestRuleDiscoverer_LocalVsGlobal(t *testing.T) {
 
 func TestRuleDiscoverer_SourcePriority(t *testing.T) {
 	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk", "rules"), 0o755)
+	os.MkdirAll(filepath.Join(dir, ".agents", "rules"), 0o755)
 	os.MkdirAll(filepath.Join(dir, ".claude", "rules"), 0o755)
-	os.WriteFile(filepath.Join(dir, ".hawk", "rules", "a.md"), []byte("# Hawk"), 0o644)
+	os.WriteFile(filepath.Join(dir, ".agents", "rules", "a.md"), []byte("# Hawk"), 0o644)
 	os.WriteFile(filepath.Join(dir, ".claude", "rules", "b.md"), []byte("# Claude"), 0o644)
 	sub := filepath.Join(dir, "src")
 	os.MkdirAll(sub, 0o755)
@@ -145,10 +145,10 @@ func TestRuleDiscoverer_SourcePriority(t *testing.T) {
 	rd := NewRuleDiscoverer(dir)
 	rules := rd.Discover(target)
 
-	// .hawk/rules (priority 1) should come before .claude/rules (priority 3)
+	// .agents/rules (priority 1) should come before .claude/rules (priority 3)
 	var hawkIdx, claudeIdx int
 	for i, r := range rules {
-		if r.Source == ".hawk/rules" {
+		if r.Source == ".agents/rules" {
 			hawkIdx = i
 		}
 		if r.Source == ".claude/rules" {
@@ -156,7 +156,7 @@ func TestRuleDiscoverer_SourcePriority(t *testing.T) {
 		}
 	}
 	if hawkIdx >= claudeIdx {
-		t.Error(".hawk/rules should have higher precedence than .claude/rules")
+		t.Error(".agents/rules should have higher precedence than .claude/rules")
 	}
 }
 
diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go
index b1ce579c..a4480f20 100644
--- a/internal/daemon/daemon.go
+++ b/internal/daemon/daemon.go
@@ -16,8 +16,8 @@ import (
 	"time"
 
 	"github.com/GrayCodeAI/hawk/internal/engine"
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/netutil"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 const maxRequestBodyBytes = 1 << 20
@@ -538,6 +538,5 @@ func (s *Server) removePIDFile() error {
 }
 
 func pidDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "run")
+	return storage.DaemonRunDir()
 }
diff --git a/internal/daemon/routes_sessions.go b/internal/daemon/routes_sessions.go
index 31093c67..9fa87e83 100644
--- a/internal/daemon/routes_sessions.go
+++ b/internal/daemon/routes_sessions.go
@@ -7,6 +7,7 @@ import (
 	"strconv"
 
 	"github.com/GrayCodeAI/hawk/internal/session"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // handleGetSession handles GET /v1/sessions/{id} — get session detail.
@@ -146,17 +147,7 @@ func (s *Server) handleDeleteSession(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 
-	home, err := os.UserHomeDir()
-	if err != nil {
-		writeJSON(w, http.StatusInternalServerError, ErrorResponse{
-			Error:   "failed to determine sessions directory",
-			Code:    "internal_error",
-			Details: err.Error(),
-		})
-		return
-	}
-
-	sessionsDir := filepath.Join(home, ".hawk", "sessions")
+	sessionsDir := storage.SessionsDir()
 	jsonlPath := filepath.Join(sessionsDir, id+".jsonl")
 	jsonPath := filepath.Join(sessionsDir, id+".json")
 
diff --git a/internal/engine/adaptive_prompt.go b/internal/engine/adaptive_prompt.go
index d451b246..c8ccc367 100644
--- a/internal/engine/adaptive_prompt.go
+++ b/internal/engine/adaptive_prompt.go
@@ -8,7 +8,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // AdaptivePrompt adjusts system prompt sections based on user corrections.
@@ -31,11 +31,10 @@ type PromptAdjustment struct {
 	LastUsed   time.Time `json:"last_used"`
 }
 
-// NewAdaptivePrompt creates an adaptive prompt backed by ~/.hawk/adaptive_prompt.json.
+// NewAdaptivePrompt creates an adaptive prompt backed by Hawk user state.
 func NewAdaptivePrompt() *AdaptivePrompt {
-	home := home.Dir()
 	ap := &AdaptivePrompt{
-		path: filepath.Join(home, ".hawk", "adaptive_prompt.json"),
+		path: filepath.Join(storage.StateDir(), "adaptive_prompt.json"),
 	}
 	ap.load()
 	return ap
diff --git a/internal/engine/bmad_features_test.go b/internal/engine/bmad_features_test.go
index 7b007330..446052cc 100644
--- a/internal/engine/bmad_features_test.go
+++ b/internal/engine/bmad_features_test.go
@@ -76,8 +76,7 @@ func TestAdversarialReview_Empty(t *testing.T) {
 
 func TestProjectContext_Load(t *testing.T) {
 	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755)
-	os.WriteFile(filepath.Join(dir, ".hawk", "project-context.md"), []byte("## Stack\n- Go 1.21\n- PostgreSQL"), 0o644)
+	os.WriteFile(filepath.Join(dir, "PROJECT_CONTEXT.md"), []byte("## Stack\n- Go 1.21\n- PostgreSQL"), 0o644)
 
 	pc := NewProjectContext(dir)
 	content := pc.Load()
diff --git a/internal/engine/coding_soul.go b/internal/engine/coding_soul.go
index 8accdd3d..f2daf730 100644
--- a/internal/engine/coding_soul.go
+++ b/internal/engine/coding_soul.go
@@ -5,11 +5,11 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // CodingSoul defines the persistent coding personality and style preferences.
-// Loaded from .hawk/soul.md — your coding DNA that hawk follows across all sessions.
+// Loaded from Hawk user state.
 type CodingSoul struct {
 	Style       string // communication style
 	Preferences string // coding preferences
@@ -18,8 +18,7 @@ type CodingSoul struct {
 
 // DefaultSoulPath returns the path to the soul file.
 func DefaultSoulPath() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "soul.md")
+	return filepath.Join(storage.StateDir(), "soul.md")
 }
 
 // LoadCodingSoul reads the soul file. Returns empty soul if not found.
@@ -27,12 +26,7 @@ func LoadCodingSoul() *CodingSoul {
 	path := DefaultSoulPath()
 	data, err := os.ReadFile(path)
 	if err != nil {
-		// Also check project-local
-		data, err = os.ReadFile(".hawk/soul.md")
-		if err != nil {
-			return &CodingSoul{Path: path}
-		}
-		path = ".hawk/soul.md"
+		return &CodingSoul{Path: path}
 	}
 	content := string(data)
 	soul := &CodingSoul{Path: path}
@@ -67,7 +61,7 @@ func (s *CodingSoul) ForPrompt() string {
 
 // InitSoulPrompt returns a prompt to generate an initial soul.md.
 func InitSoulPrompt() string {
-	return `Generate a .hawk/soul.md file based on my coding patterns. Analyze my recent code and infer:
+	return `Generate a coding soul profile for Hawk user state based on my coding patterns. Analyze my recent code and infer:
 
 ## Style
 - How I communicate (terse vs verbose, formal vs casual)
diff --git a/internal/engine/compact/session_memory.go b/internal/engine/compact/session_memory.go
index eaadcd2a..c1eb3453 100644
--- a/internal/engine/compact/session_memory.go
+++ b/internal/engine/compact/session_memory.go
@@ -8,7 +8,7 @@ import (
 	"github.com/GrayCodeAI/hawk/internal/types"
 
 	"github.com/GrayCodeAI/hawk/internal/engine/token"
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 type SessionMemoryConfig struct {
@@ -76,11 +76,10 @@ func IsCompactBoundary(m types.EyrieMessage) bool {
 }
 
 func SessionMemoryPath(sessionID string) string {
-	home := home.Dir()
 	if sessionID != "" {
-		return filepath.Join(home, ".hawk", "sessions", sessionID, "memory.md")
+		return filepath.Join(storage.SessionsDir(), sessionID, "memory.md")
 	}
-	return filepath.Join(home, ".hawk", "memory.md")
+	return filepath.Join(storage.StateDir(), "memory.md")
 }
 
 func ReadSessionMemory(sessionID string) (string, error) {
diff --git a/internal/engine/context_compaction.go b/internal/engine/context_compaction.go
index 973c9fc8..fce872c0 100644
--- a/internal/engine/context_compaction.go
+++ b/internal/engine/context_compaction.go
@@ -3,8 +3,8 @@ package engine
 import (
 	"path/filepath"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
 	"github.com/GrayCodeAI/hawk/internal/session"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/types"
 )
 
@@ -19,7 +19,7 @@ type CompactionEvent struct {
 // OnCompaction is invoked after compaction (TUI, logging, etc.).
 type OnCompaction func(CompactionEvent)
 
-// PersistID is the on-disk session id under ~/.hawk/sessions/.
+// PersistID is the on-disk session id under Hawk's user state sessions dir.
 // Set from the TUI when a chat session is created or resumed.
 func (s *Session) SetPersistID(id string) {
 	if s == nil {
@@ -97,7 +97,7 @@ func (s *Session) checkpointDir() string {
 	if id == "" {
 		return ""
 	}
-	return filepath.Join(home.Dir(), ".hawk", "sessions", id, "checkpoints")
+	return filepath.Join(storage.SessionsDir(), id, "checkpoints")
 }
 
 func (s *Session) checkpointManager() *session.CheckpointManager {
diff --git a/internal/engine/context_governor_test.go b/internal/engine/context_governor_test.go
index e8126aec..9a5f6e37 100644
--- a/internal/engine/context_governor_test.go
+++ b/internal/engine/context_governor_test.go
@@ -38,9 +38,10 @@ func TestMaybeSpillToolOutput_SmallUnchanged(t *testing.T) {
 }
 
 func TestMaybeSpillToolOutput_LargeSpills(t *testing.T) {
+	t.Setenv("HAWK_CACHE_DIR", t.TempDir())
 	in := strings.Repeat("x", toolOutputSpillMinChars+100)
 	got := maybeSpillToolOutput(in, "Bash", "call-1")
-	if !strings.Contains(got, ".hawk/scratch/") {
+	if !strings.Contains(got, "/scratch/") {
 		t.Fatalf("expected spill path in output, got %q", got[:200])
 	}
 	if strings.Contains(got, strings.Repeat("x", toolOutputSpillMinChars)) {
diff --git a/internal/engine/cost/cost_tracker.go b/internal/engine/cost/cost_tracker.go
index 6d80f85a..ba5d6f69 100644
--- a/internal/engine/cost/cost_tracker.go
+++ b/internal/engine/cost/cost_tracker.go
@@ -8,8 +8,8 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
 	analytics "github.com/GrayCodeAI/hawk/internal/observability"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 type CostTracker struct {
@@ -20,10 +20,9 @@ type CostTracker struct {
 }
 
 func NewCostTracker(sessionID string) *CostTracker {
-	home := home.Dir()
 	return &CostTracker{
 		sessionID: sessionID,
-		filePath:  filepath.Join(home, ".hawk", "cost.jsonl"),
+		filePath:  filepath.Join(storage.StateDir(), "cost.jsonl"),
 	}
 }
 
@@ -57,8 +56,7 @@ func (ct *CostTracker) Entries() []analytics.CostEntry {
 }
 
 func LoadCostHistory() ([]analytics.CostEntry, error) {
-	home := home.Dir()
-	path := filepath.Join(home, ".hawk", "cost.jsonl")
+	path := filepath.Join(storage.StateDir(), "cost.jsonl")
 	data, err := os.ReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
diff --git a/internal/engine/errs/error_context.go b/internal/engine/errs/error_context.go
index 664ab52c..3e8ab0fb 100644
--- a/internal/engine/errs/error_context.go
+++ b/internal/engine/errs/error_context.go
@@ -483,7 +483,7 @@ func NewErrorContext() *ErrorContext {
 			"Check which paths are allowed by the sandbox configuration",
 			"Request permission for the specific operation",
 			"Verify the file is within the project directory",
-			"Check sandbox settings in .hawk/settings.json",
+			"Check sandbox settings in Hawk user settings",
 		},
 		Examples: []string{
 			"// Ensure operations target files within the project root",
diff --git a/internal/engine/errs/error_patterns.go b/internal/engine/errs/error_patterns.go
index eef99024..a8e0eeb1 100644
--- a/internal/engine/errs/error_patterns.go
+++ b/internal/engine/errs/error_patterns.go
@@ -8,7 +8,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 type ErrorPattern struct {
@@ -26,9 +26,8 @@ type ErrorPatternDB struct {
 }
 
 func NewErrorPatternDB() *ErrorPatternDB {
-	home := home.Dir()
 	db := &ErrorPatternDB{
-		path: filepath.Join(home, ".hawk", "error_patterns.json"),
+		path: filepath.Join(storage.StateDir(), "error_patterns.json"),
 	}
 	db.load()
 	return db
diff --git a/internal/engine/hints_loader.go b/internal/engine/hints_loader.go
index 2e57ab12..67670b76 100644
--- a/internal/engine/hints_loader.go
+++ b/internal/engine/hints_loader.go
@@ -7,7 +7,7 @@ import (
 )
 
 // HintsFilenames are the files hawk auto-loads for project context.
-var HintsFilenames = []string{".hawkhints", "AGENTS.md", ".hawk/AGENTS.md"}
+var HintsFilenames = []string{".hawkhints", "AGENTS.md"}
 
 // HintsLoader discovers and loads project-specific hint files from the
 // working directory and subdirectories the agent explores.
diff --git a/internal/engine/integration.go b/internal/engine/integration.go
index a5966edc..bd8cf599 100644
--- a/internal/engine/integration.go
+++ b/internal/engine/integration.go
@@ -8,7 +8,7 @@ import (
 	"time"
 
 	"github.com/GrayCodeAI/hawk/internal/engine/ctxmgr"
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/types"
 	"github.com/GrayCodeAI/tok"
 )
@@ -194,7 +194,7 @@ func NewIntegrationPipeline() *IntegrationPipeline {
 	// Resolve the user's home dir once so the learning-pipeline stores do not
 	// leak into <cwd>/.hawk/ when hawk is run from inside its own source tree.
 	// See L2 in docs/plans/fix-critical-and-high-review.md.
-	homeRoot := home.Dir()
+	stateRoot := storage.StateDir()
 
 	return &IntegrationPipeline{
 		// Pre-query
@@ -221,9 +221,9 @@ func NewIntegrationPipeline() *IntegrationPipeline {
 		OutputRedactor:   NewOutputRedactor(),
 
 		// Learning
-		ExperienceStore:   NewExperienceStore(filepath.Join(homeRoot, ".hawk", "experience")),
-		KnowledgeBase:     NewKnowledgeBase(filepath.Join(homeRoot, ".hawk", "knowledge")),
-		FeedbackCollector: NewFeedbackCollector(filepath.Join(homeRoot, ".hawk", "feedback")),
+		ExperienceStore:   NewExperienceStore(filepath.Join(stateRoot, "experience")),
+		KnowledgeBase:     NewKnowledgeBase(filepath.Join(stateRoot, "knowledge")),
+		FeedbackCollector: NewFeedbackCollector(filepath.Join(stateRoot, "feedback")),
 		SelfAssessor:      NewSelfAssessor(),
 
 		// Session management
diff --git a/internal/engine/lifecycle_service.go b/internal/engine/lifecycle_service.go
index 5b0c1944..446210e4 100644
--- a/internal/engine/lifecycle_service.go
+++ b/internal/engine/lifecycle_service.go
@@ -46,7 +46,7 @@ type LifecycleService struct {
 	adaptivePrompt *AdaptivePrompt
 	// activity tracker.
 	activity *memory.ActivityTracker
-	// agents-accumulator (.hawk/agents.md).
+	// agents accumulator.
 	agentsAccum *prompts.AgentsAccumulator
 	// response cache (used in agentLoop for cache hits).
 	responseCache *ResponseCache
@@ -83,7 +83,7 @@ func NewLifecycleService(log *logger.Logger) *LifecycleService {
 
 // OnSessionStart is called by Stream() at the beginning of each session.
 // Injects learned guidelines + few-shot examples + user-preference
-// learning + .hawk/agents.md learnings into the system prompt.
+// learning + accumulated project learnings into the system prompt.
 func (s *LifecycleService) OnSessionStart(ctx context.Context, s2 *Session, lastUserMsg string) string {
 	if s.lifecycle != nil {
 		if ctx := s.lifecycle.OnSessionStart(ctx, lastUserMsg); ctx != "" {
diff --git a/internal/engine/multi_repo.go b/internal/engine/multi_repo.go
index 390da258..a37352a8 100644
--- a/internal/engine/multi_repo.go
+++ b/internal/engine/multi_repo.go
@@ -15,7 +15,7 @@ type RepoRelation struct {
 	Relation string `yaml:"relation"` // "dependency", "types", "service", "shared"
 }
 
-// MultiRepoConfig is loaded from .hawk/repos.yaml.
+// MultiRepoConfig is loaded from .agents/repos.yaml.
 type MultiRepoConfig struct {
 	Repos []RepoRelation `yaml:"repos"`
 }
@@ -26,10 +26,10 @@ type MultiRepoContext struct {
 	BaseDir string
 }
 
-// LoadMultiRepoConfig reads .hawk/repos.yaml from the project root.
+// LoadMultiRepoConfig reads .agents/repos.yaml from the project root.
 func LoadMultiRepoConfig(projectDir string) *MultiRepoContext {
 	mrc := &MultiRepoContext{BaseDir: projectDir}
-	path := filepath.Join(projectDir, ".hawk", "repos.yaml")
+	path := filepath.Join(projectDir, ".agents", "repos.yaml")
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return mrc
diff --git a/internal/engine/project/project_context.go b/internal/engine/project/project_context.go
index 5146aa31..a1a9757c 100644
--- a/internal/engine/project/project_context.go
+++ b/internal/engine/project/project_context.go
@@ -14,10 +14,10 @@ type ProjectContext struct {
 
 // ProjectContextFiles are the files hawk auto-loads for project context.
 var ProjectContextFiles = []string{
-	".hawk/project-context.md",
-	".hawk/conventions.md",
-	".hawk/architecture.md",
-	".hawk/debt.md",
+	"AGENTS.md",
+	"PROJECT_CONTEXT.md",
+	"ARCHITECTURE.md",
+	"TECH_DEBT.md",
 }
 
 // NewProjectContext creates a context loader for the given project directory.
@@ -62,7 +62,7 @@ func (pc *ProjectContext) HasContext() bool {
 
 // InitPrompt returns a prompt for hawk to generate initial project-context.md.
 func (pc *ProjectContext) InitPrompt() string {
-	return `Analyze this project and generate a .hawk/project-context.md file with:
+	return `Analyze this project and generate a PROJECT_CONTEXT.md file with:
 
 ## Technology Stack & Versions
 - List all languages, frameworks, and key dependencies with versions
diff --git a/internal/engine/prompt/prompt_optimizer.go b/internal/engine/prompt/prompt_optimizer.go
index 7a9e9d7c..583e6d05 100644
--- a/internal/engine/prompt/prompt_optimizer.go
+++ b/internal/engine/prompt/prompt_optimizer.go
@@ -9,7 +9,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/types"
 )
 
@@ -49,8 +49,7 @@ type OptimizationStep struct {
 }
 
 func NewPromptOptimizer() *PromptOptimizer {
-	home := home.Dir()
-	path := filepath.Join(home, ".hawk", "prompt_params.json")
+	path := filepath.Join(storage.StateDir(), "prompt_params.json")
 	po := &PromptOptimizer{
 		Parameters: make(map[string]*PromptParameter),
 		Path:       path,
diff --git a/internal/engine/prompt/prompt_tuner.go b/internal/engine/prompt/prompt_tuner.go
index 6fa988c2..9ada054f 100644
--- a/internal/engine/prompt/prompt_tuner.go
+++ b/internal/engine/prompt/prompt_tuner.go
@@ -9,7 +9,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 type PromptTuner struct {
@@ -28,9 +28,8 @@ type PromptVariant struct {
 }
 
 func NewPromptTuner() *PromptTuner {
-	home := home.Dir()
 	pt := &PromptTuner{
-		path: filepath.Join(home, ".hawk", "prompt_tuning.json"),
+		path: filepath.Join(storage.StateDir(), "prompt_tuning.json"),
 	}
 	pt.load()
 	return pt
diff --git a/internal/engine/scaffold/fewshot.go b/internal/engine/scaffold/fewshot.go
index 6d78d648..bca622dd 100644
--- a/internal/engine/scaffold/fewshot.go
+++ b/internal/engine/scaffold/fewshot.go
@@ -9,7 +9,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // FewShotStore collects successful (prompt, response) pairs and injects
@@ -31,10 +31,9 @@ type FewShotExample struct {
 	UsedCount int       `json:"used_count"`
 }
 
-// NewFewShotStore creates a store backed by ~/.hawk/fewshot.json.
+// NewFewShotStore creates a store backed by Hawk's user state.
 func NewFewShotStore() *FewShotStore {
-	home := home.Dir()
-	path := filepath.Join(home, ".hawk", "fewshot.json")
+	path := filepath.Join(storage.StateDir(), "fewshot.json")
 	fs := &FewShotStore{
 		path:     path,
 		maxStore: 50,
diff --git a/internal/engine/self_improve.go b/internal/engine/self_improve.go
index 73d05bf8..dd5b92da 100644
--- a/internal/engine/self_improve.go
+++ b/internal/engine/self_improve.go
@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // SelfImproveEntry records a lesson learned from a mistake.
@@ -27,8 +27,7 @@ type SelfImprover struct {
 
 // NewSelfImprover loads or creates the improvement log.
 func NewSelfImprover() *SelfImprover {
-	home := home.Dir()
-	path := filepath.Join(home, ".hawk", "self-improve.json")
+	path := filepath.Join(storage.StateDir(), "self-improve.json")
 	si := &SelfImprover{Path: path}
 	si.load()
 	return si
diff --git a/internal/engine/session.go b/internal/engine/session.go
index b9d6a043..431c67c1 100644
--- a/internal/engine/session.go
+++ b/internal/engine/session.go
@@ -281,7 +281,7 @@ func NewSessionWithClient(chat ChatClient, provider, model, systemPrompt string,
 	s.AutoCompactThresholdPct = DefaultAutoCompactThresholdPct
 	s.refreshContextWindowCache()
 
-	// Initialize agents accumulator for .hawk/agents.md
+	// Initialize agents accumulator for project learnings.
 	cwd, _ := os.Getwd()
 	s.AgentsAccum = prompts.NewAgentsAccumulator(cwd)
 
diff --git a/internal/engine/stream_tool_exec.go b/internal/engine/stream_tool_exec.go
index 568b8bb7..e6df08b8 100644
--- a/internal/engine/stream_tool_exec.go
+++ b/internal/engine/stream_tool_exec.go
@@ -409,7 +409,7 @@ func (s *Session) executeSingleTool(ctx context.Context, tc types.ToolCall, ch c
 		}
 	}
 
-	// Auto-accumulate learnings into .hawk/agents.md
+	// Auto-accumulate learnings into Hawk user state.
 	if s.AgentsAccum != nil && !isErr && (canonical == "Write" || canonical == "Edit") {
 		if p, ok := pathArgument(tc.Arguments); ok && p != "" {
 			pattern := prompts.ExtractPattern(tc.Name, p, output)
diff --git a/internal/engine/tool_output_spill.go b/internal/engine/tool_output_spill.go
index 15c9b2f9..4d4267c6 100644
--- a/internal/engine/tool_output_spill.go
+++ b/internal/engine/tool_output_spill.go
@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 const (
@@ -14,7 +16,7 @@ const (
 	toolOutputSpillPreview  = 2_000
 )
 
-// maybeSpillToolOutput writes very large tool output to .hawk/scratch/ and returns a short handle.
+// maybeSpillToolOutput writes very large tool output to Hawk's user cache and returns a short handle.
 func maybeSpillToolOutput(output, toolName, toolID string) string {
 	if len(output) <= toolOutputSpillMinChars {
 		return output
@@ -23,7 +25,7 @@ func maybeSpillToolOutput(output, toolName, toolID string) string {
 	if err != nil {
 		return truncateToolOutput(output, toolOutputSpillMinChars)
 	}
-	dir := filepath.Join(cwd, ".hawk", "scratch")
+	dir := filepath.Join(storage.ProjectCacheDir(cwd), "scratch")
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return truncateToolOutput(output, toolOutputSpillMinChars)
 	}
diff --git a/internal/engine/transfer.go b/internal/engine/transfer.go
index d84105a3..f03b4572 100644
--- a/internal/engine/transfer.go
+++ b/internal/engine/transfer.go
@@ -8,7 +8,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // TransferLearning enables cross-session knowledge transfer.
@@ -32,11 +32,10 @@ type TransferPattern struct {
 	CreatedAt   time.Time `json:"created_at"`
 }
 
-// NewTransferLearning creates a store backed by ~/.hawk/transfer.json.
+// NewTransferLearning creates a store backed by Hawk user state.
 func NewTransferLearning() *TransferLearning {
-	home := home.Dir()
 	tl := &TransferLearning{
-		path: filepath.Join(home, ".hawk", "transfer.json"),
+		path: filepath.Join(storage.StateDir(), "transfer.json"),
 	}
 	tl.load()
 	return tl
diff --git a/internal/feature/eval/cache.go b/internal/feature/eval/cache.go
index f2538bc1..60172cf9 100644
--- a/internal/feature/eval/cache.go
+++ b/internal/feature/eval/cache.go
@@ -7,7 +7,7 @@ import (
 	"os"
 	"path/filepath"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Cache stores LLM responses keyed by (model, prompt_hash, params) to avoid re-calling APIs.
@@ -24,10 +24,9 @@ type CacheEntry struct {
 	CostUSD  float64 `json:"cost_usd"`
 }
 
-// DefaultCache returns a cache at ~/.hawk/eval/cache/.
+// DefaultCache returns a cache in Hawk's user cache directory.
 func DefaultCache() *Cache {
-	home := home.Dir()
-	return &Cache{Dir: filepath.Join(home, ".hawk", "eval", "cache")}
+	return &Cache{Dir: filepath.Join(storage.CacheDir(), "eval", "cache")}
 }
 
 // Key computes a cache key from model and prompt.
diff --git a/internal/feature/eval/store.go b/internal/feature/eval/store.go
index 6b65cd08..0e7e6408 100644
--- a/internal/feature/eval/store.go
+++ b/internal/feature/eval/store.go
@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // StoredResult is the persistent JSON format for eval results.
@@ -50,10 +50,9 @@ type ResultStore struct {
 	Dir string
 }
 
-// DefaultResultStore returns a store at ~/.hawk/eval/results/.
+// DefaultResultStore returns a store in Hawk's user state directory.
 func DefaultResultStore() *ResultStore {
-	home := home.Dir()
-	return &ResultStore{Dir: filepath.Join(home, ".hawk", "eval", "results")}
+	return &ResultStore{Dir: filepath.Join(storage.StateDir(), "eval", "results")}
 }
 
 // Save writes a SuiteResult to disk as JSON.
diff --git a/internal/feature/shellmode/modes.go b/internal/feature/shellmode/modes.go
index d7b84d68..e99a13f7 100644
--- a/internal/feature/shellmode/modes.go
+++ b/internal/feature/shellmode/modes.go
@@ -5,6 +5,8 @@ import (
 	"path/filepath"
 	"strings"
 	"sync"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Mode represents the REPL routing mode.
@@ -64,22 +66,14 @@ func (mm *ModeManager) Toggle() Mode {
 }
 
 func (mm *ModeManager) persist() {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return
-	}
-	dir := filepath.Join(home, ".hawk")
+	dir := storage.StateDir()
 	_ = os.MkdirAll(dir, 0o755)
 	_ = os.WriteFile(filepath.Join(dir, "mode"), []byte(mm.current.String()), 0o644)
 }
 
 // LoadPersistedMode restores mode from disk.
 func (mm *ModeManager) LoadPersistedMode() {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return
-	}
-	data, err := os.ReadFile(filepath.Join(home, ".hawk", "mode"))
+	data, err := os.ReadFile(filepath.Join(storage.StateDir(), "mode"))
 	if err != nil {
 		return
 	}
diff --git a/internal/feature/taste/store.go b/internal/feature/taste/store.go
index 614e3b08..2eff26a3 100644
--- a/internal/feature/taste/store.go
+++ b/internal/feature/taste/store.go
@@ -7,11 +7,12 @@ import (
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 const (
 	storeVersion = 1
-	storeDirName = "taste"
 )
 
 // storeEnvelope wraps a profile with versioning metadata for serialization.
@@ -21,20 +22,16 @@ type storeEnvelope struct {
 	Profile    *Profile  `json:"profile"`
 }
 
-// Store manages file-based persistence for taste profiles at ~/.hawk/taste/.
+// Store manages file-based persistence for taste profiles.
 type Store struct {
 	baseDir string
 }
 
 // NewStore creates a store rooted at the given base directory.
-// If baseDir is empty, it defaults to ~/.hawk/taste/.
+// If baseDir is empty, it defaults to Hawk's user state taste directory.
 func NewStore(baseDir string) (*Store, error) {
 	if baseDir == "" {
-		home, err := os.UserHomeDir()
-		if err != nil {
-			return nil, fmt.Errorf("cannot determine home directory: %w", err)
-		}
-		baseDir = filepath.Join(home, ".hawk", storeDirName)
+		baseDir = storage.TasteDir()
 	}
 
 	if err := os.MkdirAll(baseDir, 0o755); err != nil {
diff --git a/internal/hooks/hooks.go b/internal/hooks/hooks.go
index b2d1e126..110c668b 100644
--- a/internal/hooks/hooks.go
+++ b/internal/hooks/hooks.go
@@ -8,6 +8,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // EventType represents a hook event.
@@ -190,25 +192,21 @@ func LoadHooksDir(dir string) error {
 	return nil
 }
 
-// LoadConventionPolicies discovers and loads policy files from .hawk/policies/ directories.
+// LoadConventionPolicies discovers and loads convention policy files.
 // Convention: auto-discovered *policy*.{md,go} files from:
-//   - {cwd}/.hawk/policies/ (project scope, git-committable)
-//   - ~/.hawk/policies/ (user scope, global)
+//   - {cwd}/.agents/policies/ (project scope)
+//   - Hawk user state policies directory
 //
 // Returns the number of policies loaded.
 func LoadConventionPolicies(cwd string) int {
 	count := 0
-	home, _ := os.UserHomeDir()
-
 	// Project scope
-	projectDir := filepath.Join(cwd, ".hawk", "policies")
+	projectDir := filepath.Join(cwd, ".agents", "policies")
 	count += loadPolicyDir(projectDir, "project")
 
 	// User scope
-	if home != "" {
-		userDir := filepath.Join(home, ".hawk", "policies")
-		count += loadPolicyDir(userDir, "user")
-	}
+	userDir := filepath.Join(storage.StateDir(), "policies")
+	count += loadPolicyDir(userDir, "user")
 
 	return count
 }
diff --git a/internal/intelligence/memory/auto_memory.go b/internal/intelligence/memory/auto_memory.go
index eb67f2a4..a61992b6 100644
--- a/internal/intelligence/memory/auto_memory.go
+++ b/internal/intelligence/memory/auto_memory.go
@@ -8,7 +8,7 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // AutoMemory manages automatic memory extraction and storage for a project.
@@ -16,12 +16,11 @@ type AutoMemory struct {
 	dir string
 }
 
-// NewAutoMemory creates a new AutoMemory rooted at ~/.hawk/projects/<hash>/memory/.
+// NewAutoMemory creates a new AutoMemory rooted in Hawk's project state.
 func NewAutoMemory(projectDir string) *AutoMemory {
 	h := sha256.Sum256([]byte(projectDir))
 	hash := fmt.Sprintf("%x", h[:8])
-	home := home.Dir()
-	dir := filepath.Join(home, ".hawk", "projects", hash, "memory")
+	dir := filepath.Join(storage.ProjectStateDir(projectDir), "memory", hash)
 	return &AutoMemory{dir: dir}
 }
 
diff --git a/internal/intelligence/memory/autodream.go b/internal/intelligence/memory/autodream.go
index 98e2d03f..278ffa3e 100644
--- a/internal/intelligence/memory/autodream.go
+++ b/internal/intelligence/memory/autodream.go
@@ -8,7 +8,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // AutoDreamConfig controls when background memory consolidation triggers.
@@ -141,6 +141,5 @@ func RunDream(ctx context.Context, cfg AutoDreamConfig, agentFn func(ctx context
 }
 
 func autoDreamMemoryDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "memory")
+	return filepath.Join(storage.StateDir(), "memory")
 }
diff --git a/internal/intelligence/memory/autofile.go b/internal/intelligence/memory/autofile.go
index 8ddea1a1..8920eff5 100644
--- a/internal/intelligence/memory/autofile.go
+++ b/internal/intelligence/memory/autofile.go
@@ -9,6 +9,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // AutoFile manages a user-visible MEMORY.md that auto-discovers project conventions.
@@ -47,7 +49,7 @@ func NewAutoFile(repoDir string) *AutoFile {
 
 // MemoryPath returns the path to the memory file.
 func (af *AutoFile) MemoryPath() string {
-	return filepath.Join(af.repoDir, ".hawk", "MEMORY.md")
+	return filepath.Join(storage.ProjectStateDir(af.repoDir), "MEMORY.md")
 }
 
 // load reads existing memory entries from MEMORY.md.
diff --git a/internal/intelligence/memory/evolving.go b/internal/intelligence/memory/evolving.go
index 9b83ca37..fc2c2ec3 100644
--- a/internal/intelligence/memory/evolving.go
+++ b/internal/intelligence/memory/evolving.go
@@ -10,7 +10,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // UsageGuideline represents a lesson learned from problem-solving experience.
@@ -28,14 +28,13 @@ type UsageGuideline struct {
 type EvolvingMemory struct {
 	mu         sync.Mutex
 	guidelines []UsageGuideline
-	path       string // ~/.hawk/memory/guidelines.json
+	path       string
 }
 
 // NewEvolvingMemory creates a new EvolvingMemory with the default storage path.
 func NewEvolvingMemory() *EvolvingMemory {
-	home := home.Dir()
 	return &EvolvingMemory{
-		path: filepath.Join(home, ".hawk", "memory", "guidelines.json"),
+		path: filepath.Join(storage.StateDir(), "memory", "guidelines.json"),
 	}
 }
 
diff --git a/internal/intelligence/memory/memory.go b/internal/intelligence/memory/memory.go
index b87a346b..c1d6b63a 100644
--- a/internal/intelligence/memory/memory.go
+++ b/internal/intelligence/memory/memory.go
@@ -8,7 +8,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Memory stores extracted memories from sessions.
@@ -21,8 +21,7 @@ type Memory struct {
 }
 
 func memoryDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "memories")
+	return filepath.Join(storage.StateDir(), "memories")
 }
 
 // Save persists a memory.
diff --git a/internal/intelligence/memory/memory_test.go b/internal/intelligence/memory/memory_test.go
index 3714ff94..6a6da7e1 100644
--- a/internal/intelligence/memory/memory_test.go
+++ b/internal/intelligence/memory/memory_test.go
@@ -3,6 +3,7 @@ package memory
 import (
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 )
@@ -275,10 +276,12 @@ func TestConsolidate_AllUnique(t *testing.T) {
 func TestMemoryDir(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
+	stateDir := filepath.Join(dir, "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
 
 	d := memoryDir()
-	if !strings.Contains(d, ".hawk") {
-		t.Errorf("memoryDir() = %q, should contain .hawk", d)
+	if !strings.HasPrefix(d, stateDir) {
+		t.Errorf("memoryDir() = %q, should be under %q", d, stateDir)
 	}
 	if !strings.Contains(d, "memories") {
 		t.Errorf("memoryDir() = %q, should contain memories", d)
diff --git a/internal/intelligence/memory/zenbrain.go b/internal/intelligence/memory/zenbrain.go
index d36072f7..a4349d95 100644
--- a/internal/intelligence/memory/zenbrain.go
+++ b/internal/intelligence/memory/zenbrain.go
@@ -10,7 +10,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // MemoryLayer identifies which layer a memory belongs to.
@@ -71,9 +71,8 @@ type ZenBrain struct {
 
 // NewZenBrain creates a new ZenBrain with the default storage path.
 func NewZenBrain() *ZenBrain {
-	home := home.Dir()
 	return &ZenBrain{
-		path: filepath.Join(home, ".hawk", "memory", "zenbrain.json"),
+		path: filepath.Join(storage.StateDir(), "memory", "zenbrain.json"),
 	}
 }
 
diff --git a/internal/intelligence/planner/planner.go b/internal/intelligence/planner/planner.go
index d4dd0a7f..5f73a5ca 100644
--- a/internal/intelligence/planner/planner.go
+++ b/internal/intelligence/planner/planner.go
@@ -1,6 +1,6 @@
 // Package planner implements structured planning that generates artifacts before
 // coding begins. It produces a Plan containing tasks, design notes, and risk
-// analysis, and can persist/load plans as JSON files under .hawk/plans/.
+// analysis, and can persist/load plans as JSON files under Hawk user state.
 package planner
 
 import (
@@ -10,6 +10,8 @@ import (
 	"path/filepath"
 	"strings"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Plan represents a structured development plan.
@@ -103,10 +105,10 @@ func ParsePlan(response string) (*Plan, error) {
 	return &plan, nil
 }
 
-// Save writes the plan to .hawk/plans/{sanitized-title}.json under the given dir.
+// Save writes the plan to Hawk project state.
 // Returns the path of the saved file.
 func Save(dir string, plan *Plan) (string, error) {
-	plansDir := filepath.Join(dir, ".hawk", "plans")
+	plansDir := storage.PlansDir(dir)
 	if err := os.MkdirAll(plansDir, 0o755); err != nil {
 		return "", fmt.Errorf("planner: cannot create plans directory: %w", err)
 	}
diff --git a/internal/intelligence/repomap/incremental_map.go b/internal/intelligence/repomap/incremental_map.go
index 00c56a75..15443c8b 100644
--- a/internal/intelligence/repomap/incremental_map.go
+++ b/internal/intelligence/repomap/incremental_map.go
@@ -1,6 +1,6 @@
 // incremental_map.go is the persistent, on-disk symbol
 // cache. It stores per-file SHA-256 hashes and the corresponding symbol
-// lists in .hawk/repomap-cache.json (or a caller-provided directory). On
+// lists in the Hawk cache directory (or a caller-provided directory). On
 // regeneration only files whose hash changed are re-parsed, and deleted
 // files are evicted, so the index stays accurate without a full rebuild.
 package repomap
@@ -12,10 +12,12 @@ import (
 	"os"
 	"path/filepath"
 	"sync"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // IncrementalMap maintains a cached symbol index that only reprocesses changed files.
-// It stores file hashes (SHA-256 of content) in a cache file (.hawk/repomap-cache.json).
+// It stores file hashes (SHA-256 of content) in a cache file.
 // On regeneration, only files whose hash changed are re-parsed. Symbols from changed
 // files are merged into the existing map, and symbols from deleted files are removed.
 type IncrementalMap struct {
@@ -32,8 +34,11 @@ type FileCache struct {
 }
 
 // NewIncrementalMap loads or creates a repomap cache.
-// cacheDir is the directory where the cache file will be stored (typically ".hawk").
+// cacheDir is the directory where the cache file will be stored.
 func NewIncrementalMap(cacheDir string) (*IncrementalMap, error) {
+	if cacheDir == "" {
+		cacheDir = storage.RepoMapCacheDir(".")
+	}
 	cacheFile := filepath.Join(cacheDir, "repomap-cache.json")
 
 	im := &IncrementalMap{
diff --git a/internal/intelligence/repomap/patterns.go b/internal/intelligence/repomap/patterns.go
index 9d1daec9..d14a1c55 100644
--- a/internal/intelligence/repomap/patterns.go
+++ b/internal/intelligence/repomap/patterns.go
@@ -1,12 +1,7 @@
-// patterns.go loads a .hawk/repomap-patterns.json file
-// (if present) describing which files to include or exclude from indexing,
-// and falls back to DefaultIndexPatterns otherwise. The result is consumed
-// by Generate, BuildSemanticIndex, and the watcher to skip unwanted trees.
+// patterns.go defines default include/exclude rules for repo indexing.
 package repomap
 
 import (
-	"encoding/json"
-	"os"
 	"path/filepath"
 )
 
@@ -57,20 +52,7 @@ func (p IndexPatterns) ShouldIndex(path string) bool {
 	return false
 }
 
-// LoadIndexPatterns reads from .hawk/index.json or uses defaults.
+// LoadIndexPatterns returns the built-in index patterns.
 func LoadIndexPatterns() IndexPatterns {
-	configPath := filepath.Join(".hawk", "index.json")
-	data, err := os.ReadFile(configPath)
-	if err != nil {
-		return DefaultIndexPatterns()
-	}
-	var patterns IndexPatterns
-	if err := json.Unmarshal(data, &patterns); err != nil {
-		return DefaultIndexPatterns()
-	}
-	// Merge with defaults: if exclude is empty, use defaults
-	if len(patterns.Exclude) == 0 {
-		patterns.Exclude = DefaultIndexPatterns().Exclude
-	}
-	return patterns
+	return DefaultIndexPatterns()
 }
diff --git a/internal/lsp/config.go b/internal/lsp/config.go
index 09c4ad4c..c6421fc5 100644
--- a/internal/lsp/config.go
+++ b/internal/lsp/config.go
@@ -10,6 +10,8 @@ import (
 	"path/filepath"
 	"strings"
 	"sync"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // ServerConfig defines how to launch a language server for a given language.
@@ -29,19 +31,16 @@ var (
 	configOnce   sync.Once
 )
 
-// LoadConfig merges project-level (.hawk/lsp.json) and global (~/.hawk/lsp.json)
+// LoadConfig merges project-level (.agents/lsp.json) and global user-state
 // LSP configuration. Project-level overrides global.
 func LoadConfig(projectDir string) *LSPConfig {
 	configOnce.Do(func() {
 		globalConfig = &LSPConfig{Servers: make(map[string]ServerConfig)}
 		// Load global config
-		home, _ := os.UserHomeDir()
-		if home != "" {
-			loadConfigFile(filepath.Join(home, ".hawk", "lsp.json"), globalConfig)
-		}
+		loadConfigFile(filepath.Join(storage.StateDir(), "lsp.json"), globalConfig)
 		// Load project config (overrides global)
 		if projectDir != "" {
-			loadConfigFile(filepath.Join(projectDir, ".hawk", "lsp.json"), globalConfig)
+			loadConfigFile(filepath.Join(projectDir, ".agents", "lsp.json"), globalConfig)
 		}
 		// Apply built-in defaults for unconfigured languages
 		applyDefaults(globalConfig)
diff --git a/internal/multiagent/agents/agents.go b/internal/multiagent/agents/agents.go
index 31251823..317ec95a 100644
--- a/internal/multiagent/agents/agents.go
+++ b/internal/multiagent/agents/agents.go
@@ -6,11 +6,11 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Agent is a user-defined persona with a custom system prompt.
-// Stored as markdown files with YAML frontmatter in ~/.hawk/agents/.
+// Stored as markdown files with YAML frontmatter in Hawk user state.
 type Agent struct {
 	Name        string `json:"name"`
 	Description string `json:"description"`
@@ -87,8 +87,7 @@ func Parse(content, filePath string) (*Agent, error) {
 	return agent, nil
 }
 
-// ListAll discovers all agent definitions from the standard directories.
-// Search order: ~/.hawk/agents/, .hawk/agents/ (project-local).
+// ListAll discovers all agent definitions from Hawk user state.
 func ListAll() ([]*Agent, error) {
 	var agents []*Agent
 
@@ -126,25 +125,14 @@ func Get(name string) (*Agent, error) {
 	return nil, fmt.Errorf("agent %q not found", name)
 }
 
-// DefaultDir returns the user's agent directory (~/.hawk/agents/).
+// DefaultDir returns the user's agent directory.
 func DefaultDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "agents")
+	return storage.PersonasDir()
 }
 
 // agentDirs returns the list of directories to search for agents.
 func agentDirs() []string {
-	dirs := []string{DefaultDir()}
-
-	// Project-local agents
-	if cwd, err := os.Getwd(); err == nil {
-		localDir := filepath.Join(cwd, ".hawk", "agents")
-		if info, err := os.Stat(localDir); err == nil && info.IsDir() {
-			dirs = append(dirs, localDir)
-		}
-	}
-
-	return dirs
+	return []string{DefaultDir()}
 }
 
 func parseYAMLLine(line string) (key, val string, ok bool) {
diff --git a/internal/multiagent/agents/agents_test.go b/internal/multiagent/agents/agents_test.go
index aabebead..adec6459 100644
--- a/internal/multiagent/agents/agents_test.go
+++ b/internal/multiagent/agents/agents_test.go
@@ -107,8 +107,9 @@ func TestListAll_FromDir(t *testing.T) {
 	}
 	defer os.Setenv("HOME", origHome) //nolint:errcheck
 
-	// Create ~/.hawk/agents
-	agentDir := filepath.Join(dir, ".hawk", "agents")
+	stateDir := filepath.Join(dir, "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
+	agentDir := filepath.Join(stateDir, "agents")
 	if err := os.MkdirAll(agentDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -121,7 +122,7 @@ func TestListAll_FromDir(t *testing.T) {
 		t.Fatalf("ListAll failed: %v", err)
 	}
 	if len(agents) < 1 {
-		t.Error("expected at least 1 agent from ~/.hawk/agents/")
+		t.Error("expected at least 1 agent from user state agents dir")
 	}
 }
 
diff --git a/internal/multiagent/agents/persona.go b/internal/multiagent/agents/persona.go
index a9b28250..868e8347 100644
--- a/internal/multiagent/agents/persona.go
+++ b/internal/multiagent/agents/persona.go
@@ -11,7 +11,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Persona represents an enhanced agent definition with specific skills,
@@ -69,11 +69,10 @@ type PersonaRegistry struct {
 }
 
 // NewPersonaRegistry creates a new registry with the given storage directory.
-// If dir is empty, it defaults to ~/.hawk/agents/.
+// If dir is empty, it defaults to Hawk's user state agents directory.
 func NewPersonaRegistry(dir string) *PersonaRegistry {
 	if dir == "" {
-		home := home.Dir()
-		dir = filepath.Join(home, ".hawk", "agents")
+		dir = storage.PersonasDir()
 	}
 	return &PersonaRegistry{
 		Personas: make(map[string]*Persona),
diff --git a/internal/multiagent/agents/persona_registry_test.go b/internal/multiagent/agents/persona_registry_test.go
index 052c86a0..8a076766 100644
--- a/internal/multiagent/agents/persona_registry_test.go
+++ b/internal/multiagent/agents/persona_registry_test.go
@@ -533,12 +533,18 @@ func TestParsePersonaFile_NameFromFilename(t *testing.T) {
 }
 
 func TestNewPersonaRegistry_DefaultDir(t *testing.T) {
+	stateDir := t.TempDir()
+	t.Setenv("HAWK_STATE_DIR", stateDir)
+
 	r := NewPersonaRegistry("")
 	if r.Dir == "" {
 		t.Error("default dir should not be empty")
 	}
-	if !strings.Contains(r.Dir, ".hawk") {
-		t.Errorf("default dir should contain .hawk, got %q", r.Dir)
+	if strings.Contains(r.Dir, ".hawk") {
+		t.Errorf("default dir should not contain .hawk, got %q", r.Dir)
+	}
+	if !strings.HasPrefix(r.Dir, stateDir) {
+		t.Errorf("default dir should be under state dir %q, got %q", stateDir, r.Dir)
 	}
 }
 
diff --git a/internal/multiagent/parallel/worktree_manager.go b/internal/multiagent/parallel/worktree_manager.go
index d521754a..8277222e 100644
--- a/internal/multiagent/parallel/worktree_manager.go
+++ b/internal/multiagent/parallel/worktree_manager.go
@@ -11,6 +11,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // WorktreeStatus represents the lifecycle state of a managed worktree.
@@ -63,7 +65,7 @@ func generateID() string {
 }
 
 // Create creates a new git worktree on a new branch derived from baseBranch.
-// The worktree is stored under .hawk/worktrees/ within the base directory.
+// The worktree is stored under Hawk's project state directory.
 func (wm *WorktreeManager) Create(branch, baseBranch, taskDescription string) (*Worktree, error) {
 	wm.mu.Lock()
 	defer wm.mu.Unlock()
@@ -80,7 +82,7 @@ func (wm *WorktreeManager) Create(branch, baseBranch, taskDescription string) (*
 	}
 
 	id := generateID()
-	wtDir := filepath.Join(wm.BaseDir, ".hawk", "worktrees", id)
+	wtDir := filepath.Join(storage.ProjectStateDir(wm.BaseDir), "worktrees", id)
 
 	cmd := exec.CommandContext(context.Background(), "git", "worktree", "add", "-b", branch, wtDir, baseBranch)
 	cmd.Dir = wm.BaseDir
diff --git a/internal/observability/analytics.go b/internal/observability/analytics.go
index 339a66ed..d7ca2b42 100644
--- a/internal/observability/analytics.go
+++ b/internal/observability/analytics.go
@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Event represents an analytics event.
@@ -19,8 +19,7 @@ type Event struct {
 }
 
 func analyticsDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "analytics")
+	return filepath.Join(storage.StateDir(), "analytics")
 }
 
 // LogEvent logs an analytics event.
diff --git a/internal/observability/analytics_test.go b/internal/observability/analytics_test.go
index 41b1d94b..6e5b91d6 100644
--- a/internal/observability/analytics_test.go
+++ b/internal/observability/analytics_test.go
@@ -2,6 +2,7 @@ package analytics
 
 import (
 	"os"
+	"path/filepath"
 	"strings"
 	"testing"
 	"time"
@@ -10,11 +11,13 @@ import (
 func TestLogEvent(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
+	stateDir := filepath.Join(dir, "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
 
 	LogEvent("test_event", "session-123", map[string]interface{}{"key": "value"})
 
 	// Verify file was created
-	data, err := os.ReadFile(dir + "/.hawk/analytics/events.jsonl")
+	data, err := os.ReadFile(filepath.Join(stateDir, "analytics", "events.jsonl"))
 	if err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/observability/insights.go b/internal/observability/insights.go
index 994713e3..85c5c404 100644
--- a/internal/observability/insights.go
+++ b/internal/observability/insights.go
@@ -9,7 +9,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // InsightsFacet represents an extracted insight category.
@@ -139,8 +139,7 @@ h1 { color: #333; } h2 { color: #555; border-bottom: 1px solid #eee; }
 
 // SaveInsightsReport saves an HTML report to disk.
 func SaveInsightsReport(report *InsightsReport) (string, error) {
-	home := home.Dir()
-	dir := filepath.Join(home, ".hawk", "insights")
+	dir := filepath.Join(storage.StateDir(), "insights")
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return "", err
 	}
@@ -203,6 +202,5 @@ func generateRecommendations(patterns []string, sessionCount int) []string {
 }
 
 func sessionsDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "sessions")
+	return storage.SessionsDir()
 }
diff --git a/internal/permissions/persist.go b/internal/permissions/persist.go
index 89d68808..61cb8a22 100644
--- a/internal/permissions/persist.go
+++ b/internal/permissions/persist.go
@@ -5,6 +5,8 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Rule is defined in rules.go with the Action type.
@@ -52,5 +54,5 @@ func Load(path string) ([]Rule, error) {
 
 // DefaultPath returns the default permissions file path for a project directory.
 func DefaultPath(projectDir string) string {
-	return filepath.Join(projectDir, ".hawk", "permissions.json")
+	return filepath.Join(storage.ProjectStateDir(projectDir), "permissions.json")
 }
diff --git a/internal/permissions/rules_test.go b/internal/permissions/rules_test.go
index 810fe7df..33725d2f 100644
--- a/internal/permissions/rules_test.go
+++ b/internal/permissions/rules_test.go
@@ -292,7 +292,7 @@ func TestSaveAndLoadRoundTrip(t *testing.T) {
 	}
 
 	dir := t.TempDir()
-	path := filepath.Join(dir, ".hawk", "rules")
+	path := filepath.Join(dir, ".agents", "rules")
 
 	if err := original.SaveToFile(path); err != nil {
 		t.Fatalf("SaveToFile error: %v", err)
diff --git a/internal/plugin/auto_skill.go b/internal/plugin/auto_skill.go
index bf1d35c2..f28c4a9c 100644
--- a/internal/plugin/auto_skill.go
+++ b/internal/plugin/auto_skill.go
@@ -171,7 +171,7 @@ func RunAutoSkill(dir string) (string, error) {
 
 	installed := 0
 	for _, skill := range recommended {
-		msg, err := rc.Install(skill.Repo, skill.Name, "project")
+		msg, err := rc.Install(skill.Repo, skill.Name, "user")
 		if err != nil {
 			_, _ = fmt.Fprintf(&b, "  "+icons.CloseThick()+" %s — %v\n", skill.Name, err)
 			continue
@@ -182,7 +182,7 @@ func RunAutoSkill(dir string) (string, error) {
 	}
 
 	if installed > 0 {
-		_, _ = fmt.Fprintf(&b, "\nInstalled %d skill(s) to .hawk/skills/", installed)
+		_, _ = fmt.Fprintf(&b, "\nInstalled %d skill(s) to Hawk user state", installed)
 	}
 	return b.String(), nil
 }
diff --git a/internal/plugin/auto_skill_audit_test.go b/internal/plugin/auto_skill_audit_test.go
index a2dd6654..5e10caa3 100644
--- a/internal/plugin/auto_skill_audit_test.go
+++ b/internal/plugin/auto_skill_audit_test.go
@@ -239,7 +239,7 @@ func TestDefaultSkillDirsCrossAgent(t *testing.T) {
 		if strings.Contains(d, ".codex/skills") {
 			found["codex"] = true
 		}
-		if strings.Contains(d, ".hawk/skills") {
+		if strings.Contains(d, "hawk") && strings.Contains(d, "skills") && !strings.Contains(d, ".hawk/skills") {
 			found["hawk"] = true
 		}
 	}
@@ -248,7 +248,7 @@ func TestDefaultSkillDirsCrossAgent(t *testing.T) {
 			t.Errorf("expected %s skills directory", agent)
 		}
 	}
-	if len(dirs) < 8 {
-		t.Errorf("expected at least 8 dirs, got %d", len(dirs))
+	if len(dirs) < 7 {
+		t.Errorf("expected at least 7 dirs, got %d", len(dirs))
 	}
 }
diff --git a/internal/plugin/bundled_skills.go b/internal/plugin/bundled_skills.go
index b48d332f..ec52b86f 100644
--- a/internal/plugin/bundled_skills.go
+++ b/internal/plugin/bundled_skills.go
@@ -6,7 +6,7 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // BundledSkill defines a skill that ships with hawk.
@@ -169,8 +169,7 @@ category: general
 
 // BundledSkillsDir returns the directory where bundled skills are extracted.
 func BundledSkillsDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "bundled-skills")
+	return storage.BundledSkillsDir()
 }
 
 // ExtractBundledSkills extracts bundled skills to the user directory.
diff --git a/internal/plugin/dynamic.go b/internal/plugin/dynamic.go
index 972cc229..4a0d6c60 100644
--- a/internal/plugin/dynamic.go
+++ b/internal/plugin/dynamic.go
@@ -12,7 +12,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // PluginState represents the lifecycle state of a dynamic plugin.
@@ -132,10 +132,8 @@ type DynamicPluginManager struct {
 // NewDynamicPluginManager creates a new DynamicPluginManager with the given directories and registries.
 func NewDynamicPluginManager(dirs []string, tools ToolRegistrar, hooks HookRegistrar) *DynamicPluginManager {
 	if len(dirs) == 0 {
-		home := home.Dir()
 		dirs = []string{
-			filepath.Join(home, ".hawk", "plugins"),
-			filepath.Join(".hawk", "plugins"),
+			filepath.Join(storage.StateDir(), "plugins"),
 		}
 	}
 	return &DynamicPluginManager{
@@ -388,8 +386,7 @@ func (dm *DynamicPluginManager) Get(name string) (*DynamicPlugin, bool) {
 
 // InstallFromGitHub clones a repo into the plugins directory.
 func (dm *DynamicPluginManager) InstallFromGitHub(repo string) error {
-	home := home.Dir()
-	destDir := filepath.Join(home, ".hawk", "plugins")
+	destDir := filepath.Join(storage.StateDir(), "plugins")
 	if err := os.MkdirAll(destDir, 0o755); err != nil {
 		return fmt.Errorf("create plugins dir: %w", err)
 	}
diff --git a/internal/plugin/feedback.go b/internal/plugin/feedback.go
index 9b56a073..21612598 100644
--- a/internal/plugin/feedback.go
+++ b/internal/plugin/feedback.go
@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // SkillRating stores a user's rating for a skill.
@@ -23,10 +23,9 @@ type FeedbackStore struct {
 	path string
 }
 
-// NewFeedbackStore creates a store at ~/.hawk/feedback.json.
+// NewFeedbackStore creates a store in Hawk's user state directory.
 func NewFeedbackStore() *FeedbackStore {
-	home := home.Dir()
-	return &FeedbackStore{path: filepath.Join(home, ".hawk", "feedback.json")}
+	return &FeedbackStore{path: filepath.Join(storage.StateDir(), "feedback.json")}
 }
 
 // NewFeedbackStoreAt creates a store at a custom path (for testing).
diff --git a/internal/plugin/manager.go b/internal/plugin/manager.go
index 9594e55e..0651e260 100644
--- a/internal/plugin/manager.go
+++ b/internal/plugin/manager.go
@@ -14,7 +14,7 @@ import (
 	"time"
 	"unicode"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Plugin represents a loaded plugin with its tools and metadata.
@@ -97,13 +97,11 @@ type SecurityIssue struct {
 }
 
 // NewPluginManager creates a new PluginManager with the given directories.
-// If no directories are provided, defaults to ~/.hawk/plugins/ and .hawk/plugins/.
+// If no directories are provided, defaults to Hawk user state.
 func NewPluginManager(dirs ...string) *PluginManager {
 	if len(dirs) == 0 {
-		home := home.Dir()
 		dirs = []string{
-			filepath.Join(home, ".hawk", "plugins"),
-			filepath.Join(".hawk", "plugins"),
+			filepath.Join(storage.StateDir(), "plugins"),
 		}
 	}
 	return &PluginManager{
diff --git a/internal/plugin/manager_test.go b/internal/plugin/manager_test.go
index c2aa2392..2d59ef06 100644
--- a/internal/plugin/manager_test.go
+++ b/internal/plugin/manager_test.go
@@ -9,6 +9,8 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 func TestParseManifestValid(t *testing.T) {
@@ -670,17 +672,13 @@ func TestMultiplePluginsSameToolNameNamespacing(t *testing.T) {
 
 func TestNewPluginManagerDefaultDirs(t *testing.T) {
 	pm := NewPluginManager()
-	if len(pm.PluginDirs) != 2 {
-		t.Fatalf("expected 2 default dirs, got %d", len(pm.PluginDirs))
+	if len(pm.PluginDirs) != 1 {
+		t.Fatalf("expected 1 default dir, got %d", len(pm.PluginDirs))
 	}
 
-	home, _ := os.UserHomeDir()
-	if pm.PluginDirs[0] != filepath.Join(home, ".hawk", "plugins") {
+	if pm.PluginDirs[0] != filepath.Join(storage.StateDir(), "plugins") {
 		t.Errorf("unexpected first dir: %s", pm.PluginDirs[0])
 	}
-	if pm.PluginDirs[1] != filepath.Join(".hawk", "plugins") {
-		t.Errorf("unexpected second dir: %s", pm.PluginDirs[1])
-	}
 }
 
 func TestLoadReturnsAlreadyLoaded(t *testing.T) {
diff --git a/internal/plugin/plugin.go b/internal/plugin/plugin.go
index 0f589ded..f6ea0b33 100644
--- a/internal/plugin/plugin.go
+++ b/internal/plugin/plugin.go
@@ -6,7 +6,7 @@ import (
 	"os"
 	"path/filepath"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Manifest defines a hawk plugin.
@@ -62,8 +62,7 @@ func (m *Manifest) Validate() error {
 }
 
 func pluginsDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "plugins")
+	return filepath.Join(storage.StateDir(), "plugins")
 }
 
 // LoadManifest loads a plugin manifest from a directory.
diff --git a/internal/plugin/registry.go b/internal/plugin/registry.go
index 1ba6b078..20b122de 100644
--- a/internal/plugin/registry.go
+++ b/internal/plugin/registry.go
@@ -13,7 +13,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 const defaultIndexURL = "https://raw.githubusercontent.com/GrayCodeAI/hawk-community-skills/main/registry.json"
@@ -50,10 +50,9 @@ type RegistryClient struct {
 
 // NewRegistryClient creates a registry client with sensible defaults.
 func NewRegistryClient() *RegistryClient {
-	home := home.Dir()
 	return &RegistryClient{
 		IndexURL: defaultIndexURL,
-		CacheDir: filepath.Join(home, ".hawk", "cache"),
+		CacheDir: filepath.Join(storage.CacheDir(), "skills"),
 		client:   &http.Client{Timeout: 15 * time.Second},
 	}
 }
@@ -194,13 +193,12 @@ func (rc *RegistryClient) Info(name string) (*SkillEntry, error) {
 // Install clones a specific skill from a GitHub repo into the skills directory.
 // If skillName is empty, all skills in the repo are installed.
 func (rc *RegistryClient) Install(repo, skillName, scope string) (string, error) {
-	home := home.Dir()
 	var destBase string
 	switch scope {
 	case "user":
-		destBase = filepath.Join(home, ".hawk", "skills")
+		destBase = filepath.Join(storage.StateDir(), "skills")
 	default: // "project"
-		destBase = filepath.Join(".hawk", "skills")
+		destBase = filepath.Join(storage.ProjectStateDir("."), "skills")
 	}
 	_ = os.MkdirAll(destBase, 0o755)
 
@@ -285,12 +283,10 @@ func (rc *RegistryClient) Install(repo, skillName, scope string) (string, error)
 	return fmt.Sprintf("Installed %d skill(s): %s", len(installed), strings.Join(installed, ", ")), nil
 }
 
-// Remove uninstalls a skill by name from both project and user scope.
+// Remove uninstalls a skill by name from Hawk user state.
 func Remove(name string) error {
-	home := home.Dir()
 	dirs := []string{
-		filepath.Join(".hawk", "skills", name),
-		filepath.Join(home, ".hawk", "skills", name),
+		filepath.Join(storage.StateDir(), "skills", name),
 	}
 	removed := false
 	for _, d := range dirs {
@@ -307,10 +303,8 @@ func Remove(name string) error {
 
 // InstalledSkillInfo returns source metadata for an installed skill.
 func InstalledSkillInfo(name string) (SmartSkill, string, bool) {
-	home := home.Dir()
 	dirs := []string{
-		filepath.Join(".hawk", "skills"),
-		filepath.Join(home, ".hawk", "skills"),
+		filepath.Join(storage.StateDir(), "skills"),
 	}
 	for _, dir := range dirs {
 		skillFile := filepath.Join(dir, name, "SKILL.md")
diff --git a/internal/plugin/skills_auto.go b/internal/plugin/skills_auto.go
index 5321722c..88e93683 100644
--- a/internal/plugin/skills_auto.go
+++ b/internal/plugin/skills_auto.go
@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // SkillSource tracks where an installed skill came from.
@@ -351,18 +352,17 @@ func ParseSmartSkillPublic(content string) SmartSkill {
 func DefaultSkillDirs() []string {
 	home := home.Dir()
 	if home == "" {
-		return []string{".hawk/skills", ".agents/skills"}
+		return []string{".agents/skills"}
 	}
 	return []string{
 		// Project-level directories.
-		".hawk/skills",   // hawk project skills
 		".agents/skills", // agentskills.io shared dir (gh skill install default)
 		".claude/skills", // Claude Code project skills
 		".codex/skills",  // Codex project skills
 		// User-level directories.
-		filepath.Join(home, ".hawk", "skills"),   // hawk global skills
-		filepath.Join(home, ".agents", "skills"), // agentskills.io global shared
-		filepath.Join(home, ".claude", "skills"), // Claude Code global skills
-		filepath.Join(home, ".codex", "skills"),  // Codex global skills
+		filepath.Join(storage.StateDir(), "skills"), // hawk global skills
+		filepath.Join(home, ".agents", "skills"),    // agentskills.io global shared
+		filepath.Join(home, ".claude", "skills"),    // Claude Code global skills
+		filepath.Join(home, ".codex", "skills"),     // Codex global skills
 	}
 }
diff --git a/internal/plugin/wizard.go b/internal/plugin/wizard.go
index ec1f06f7..6abd40ea 100644
--- a/internal/plugin/wizard.go
+++ b/internal/plugin/wizard.go
@@ -5,6 +5,8 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // BuildNewSkillPrompt creates an LLM prompt for the skill creator wizard.
@@ -49,9 +51,9 @@ allowed-tools: Read Write Bash Grep
 ...`, description)
 }
 
-// SaveNewSkill writes a SKILL.md to the project skills directory.
+// SaveNewSkill writes a SKILL.md to Hawk user state.
 func SaveNewSkill(name, content string) (string, error) {
-	dir := filepath.Join(".hawk", "skills", name)
+	dir := filepath.Join(storage.StateDir(), "skills", name)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		return "", fmt.Errorf("create skill dir: %w", err)
 	}
diff --git a/internal/prompts/agents_accumulator.go b/internal/prompts/agents_accumulator.go
index cf71ff1a..8c8b42c9 100644
--- a/internal/prompts/agents_accumulator.go
+++ b/internal/prompts/agents_accumulator.go
@@ -1,5 +1,5 @@
 // Package prompts manages workspace context for hawk sessions.
-// This file implements auto-accumulation of learnings into .hawk/agents.md.
+// This file implements auto-accumulation of learnings into Hawk user state.
 package prompts
 
 import (
@@ -9,10 +9,12 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // AgentsAccumulator captures learnings from successful edits and appends
-// them to .hawk/agents.md for future sessions to benefit from.
+// them to user state for future sessions to benefit from.
 type AgentsAccumulator struct {
 	projectDir string
 	filePath   string
@@ -32,7 +34,7 @@ type Learning struct {
 func NewAgentsAccumulator(projectDir string) *AgentsAccumulator {
 	return &AgentsAccumulator{
 		projectDir: projectDir,
-		filePath:   filepath.Join(projectDir, ".hawk", "agents.md"),
+		filePath:   filepath.Join(storage.ProjectStateDir(projectDir), "agents.md"),
 	}
 }
 
@@ -49,7 +51,7 @@ func (a *AgentsAccumulator) Record(context string, pattern string, files []strin
 	})
 }
 
-// Flush writes all buffered learnings to .hawk/agents.md.
+// Flush writes all buffered learnings to Hawk user state.
 func (a *AgentsAccumulator) Flush() error {
 	a.mu.Lock()
 	learnings := make([]Learning, len(a.buffer))
@@ -61,10 +63,9 @@ func (a *AgentsAccumulator) Flush() error {
 		return nil
 	}
 
-	// Ensure .hawk directory exists
 	dir := filepath.Dir(a.filePath)
 	if err := os.MkdirAll(dir, 0o755); err != nil {
-		return fmt.Errorf("creating .hawk directory: %w", err)
+		return fmt.Errorf("creating agents accumulator directory: %w", err)
 	}
 
 	// Read existing content
diff --git a/internal/prompts/agents_accumulator_test.go b/internal/prompts/agents_accumulator_test.go
index 185d72e6..d86a3738 100644
--- a/internal/prompts/agents_accumulator_test.go
+++ b/internal/prompts/agents_accumulator_test.go
@@ -5,6 +5,8 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 func TestNewAgentsAccumulator(t *testing.T) {
@@ -13,7 +15,7 @@ func TestNewAgentsAccumulator(t *testing.T) {
 	if acc == nil {
 		t.Fatal("expected non-nil accumulator")
 	}
-	if acc.filePath != filepath.Join(dir, ".hawk", "agents.md") {
+	if acc.filePath != filepath.Join(storage.ProjectStateDir(dir), "agents.md") {
 		t.Errorf("unexpected path: %s", acc.filePath)
 	}
 }
diff --git a/internal/prompts/loader.go b/internal/prompts/loader.go
index 9b953c88..35e1fa4e 100644
--- a/internal/prompts/loader.go
+++ b/internal/prompts/loader.go
@@ -10,6 +10,8 @@ import (
 	"strings"
 	"text/template"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 //go:embed templates/*.md
@@ -46,7 +48,7 @@ func DefaultContext() PromptContext {
 }
 
 // BuildSystemPrompt assembles the main template sections into a complete system prompt.
-// It checks ~/.hawk/prompts/ first for user overrides, then falls back to embedded templates.
+// It checks Hawk user config first for user overrides, then falls back to embedded templates.
 func BuildSystemPrompt(ctx PromptContext) (string, error) {
 	var sections []string
 	for _, name := range mainSections {
@@ -73,15 +75,12 @@ func BuildSubAgentPrompt(ctx PromptContext) (string, error) {
 }
 
 // LoadTemplate loads a single template by name.
-// It checks ~/.hawk/prompts/<name> first (user overrides), then falls back to embedded.
+// It checks Hawk user config prompts first, then falls back to embedded.
 func LoadTemplate(name string) (string, error) {
 	// Check user override directory first
-	home, err := os.UserHomeDir()
-	if err == nil {
-		overridePath := filepath.Join(home, ".hawk", "prompts", name)
-		if data, readErr := os.ReadFile(overridePath); readErr == nil {
-			return string(data), nil
-		}
+	overridePath := filepath.Join(storage.ConfigDir(), "prompts", name)
+	if data, readErr := os.ReadFile(overridePath); readErr == nil {
+		return string(data), nil
 	}
 
 	// Fall back to embedded templates
diff --git a/internal/recipe/providers.go b/internal/recipe/providers.go
index 7cb612de..0828b1af 100644
--- a/internal/recipe/providers.go
+++ b/internal/recipe/providers.go
@@ -7,7 +7,7 @@ import (
 	"os"
 	"path/filepath"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"gopkg.in/yaml.v3"
 )
 
@@ -70,10 +70,9 @@ func LoadProviderConfigs(dir string) ([]ProviderConfig, error) {
 
 // DefaultProviderConfigDirs returns standard directories for provider configs.
 func DefaultProviderConfigDirs() []string {
-	home := home.Dir()
 	return []string{
-		filepath.Join(home, ".hawk", "providers"),
-		".hawk/providers",
+		filepath.Join(storage.StateDir(), "providers"),
+		filepath.Join(".agents", "providers"),
 	}
 }
 
diff --git a/internal/recipe/recipe.go b/internal/recipe/recipe.go
index 4411e896..d5d675a6 100644
--- a/internal/recipe/recipe.go
+++ b/internal/recipe/recipe.go
@@ -11,7 +11,7 @@ import (
 	"text/template"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"gopkg.in/yaml.v3"
 )
 
@@ -153,11 +153,10 @@ type Runner struct {
 
 // NewRunner creates a recipe runner with default directories.
 func NewRunner() *Runner {
-	home := home.Dir()
 	return &Runner{
 		RecipeDirs: []string{
-			filepath.Join(home, ".hawk", "recipes"),
-			".hawk/recipes",
+			filepath.Join(storage.StateDir(), "recipes"),
+			filepath.Join(".agents", "recipes"),
 		},
 		Timeout: 30 * time.Minute,
 	}
diff --git a/internal/resilience/health/diagnostics.go b/internal/resilience/health/diagnostics.go
index ff807c03..85009e09 100644
--- a/internal/resilience/health/diagnostics.go
+++ b/internal/resilience/health/diagnostics.go
@@ -14,6 +14,7 @@ import (
 
 	"github.com/GrayCodeAI/eyrie/credentials"
 	"github.com/GrayCodeAI/hawk/internal/config"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 
 	"github.com/GrayCodeAI/hawk/internal/ui/icons"
 )
@@ -298,18 +299,7 @@ func checkDiskSpace() DiagnosticResult {
 
 func checkConfigFileValid() DiagnosticResult {
 	start := time.Now()
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return DiagnosticResult{
-			Name:     "config_file_valid",
-			Status:   "warn",
-			Message:  "Could not determine home directory",
-			Fix:      "Set HOME environment variable",
-			Duration: time.Since(start),
-		}
-	}
-
-	configPath := filepath.Join(home, ".hawk", "config.json")
+	configPath := filepath.Join(storage.ConfigDir(), "config.json")
 	info, err := os.Stat(configPath)
 	if os.IsNotExist(err) {
 		return DiagnosticResult{
@@ -325,7 +315,7 @@ func checkConfigFileValid() DiagnosticResult {
 			Name:     "config_file_valid",
 			Status:   "fail",
 			Message:  fmt.Sprintf("Error accessing config: %v", err),
-			Fix:      "Check file permissions on ~/.hawk/config.json",
+			Fix:      "Check file permissions on Hawk's config directory",
 			Duration: time.Since(start),
 		}
 	}
@@ -390,18 +380,7 @@ func checkModelConfigured() DiagnosticResult {
 
 func checkSessionDirWritable() DiagnosticResult {
 	start := time.Now()
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return DiagnosticResult{
-			Name:     "session_dir_writable",
-			Status:   "fail",
-			Message:  "Could not determine home directory",
-			Fix:      "Set HOME environment variable",
-			Duration: time.Since(start),
-		}
-	}
-
-	sessionDir := filepath.Join(home, ".hawk", "sessions")
+	sessionDir := storage.SessionsDir()
 	return checkDirWritable("session_dir_writable", sessionDir, start)
 }
 
@@ -465,17 +444,7 @@ func checkNodeBinary() DiagnosticResult {
 
 func checkConfigDirWritable() DiagnosticResult {
 	start := time.Now()
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return DiagnosticResult{
-			Name:     "config_dir_writable",
-			Status:   "fail",
-			Message:  "Could not determine home directory",
-			Fix:      "Set HOME environment variable",
-			Duration: time.Since(start),
-		}
-	}
-	configDir := filepath.Join(home, ".hawk")
+	configDir := storage.ConfigDir()
 	return checkDirWritable("config_dir_writable", configDir, start)
 }
 
diff --git a/internal/rules/formats.go b/internal/rules/formats.go
index acabf4f9..34b3ed33 100644
--- a/internal/rules/formats.go
+++ b/internal/rules/formats.go
@@ -7,16 +7,16 @@ import (
 )
 
 // ---------------------------------------------------------------------------
-// Hawk: .hawk/rules/*.md
+// Hawk: .agents/rules/*.md
 // ---------------------------------------------------------------------------
 
 func readHawk(dir string) ([]Rule, error) {
-	rulesDir := filepath.Join(dir, ".hawk", "rules")
+	rulesDir := filepath.Join(dir, ".agents", "rules")
 	return readMDDir(rulesDir, ".md", FormatHawk)
 }
 
 func writeHawk(dir string, rules []Rule) error {
-	rulesDir := filepath.Join(dir, ".hawk", "rules")
+	rulesDir := filepath.Join(dir, ".agents", "rules")
 	if err := os.MkdirAll(rulesDir, 0o755); err != nil {
 		return err
 	}
diff --git a/internal/rules/formats_test.go b/internal/rules/formats_test.go
index c36f1e49..10fbd7d6 100644
--- a/internal/rules/formats_test.go
+++ b/internal/rules/formats_test.go
@@ -342,7 +342,7 @@ func TestFormatCandidates_Hawk(t *testing.T) {
 	if len(candidates) != 1 {
 		t.Fatalf("expected 1 candidate, got %d", len(candidates))
 	}
-	if candidates[0] != filepath.Join("/project", ".hawk", "rules") {
+	if candidates[0] != filepath.Join("/project", ".agents", "rules") {
 		t.Errorf("unexpected path: %q", candidates[0])
 	}
 }
diff --git a/internal/rules/rules.go b/internal/rules/rules.go
index 5d51ccc9..a4b54abf 100644
--- a/internal/rules/rules.go
+++ b/internal/rules/rules.go
@@ -11,7 +11,7 @@ import (
 type Format string
 
 const (
-	FormatHawk       Format = "hawk"       // .hawk/rules/*.md
+	FormatHawk       Format = "hawk"       // .agents/rules/*.md
 	FormatCursor     Format = "cursor"     // .cursorrules or .cursor/rules/*.mdc
 	FormatClaudeCode Format = "claudecode" // CLAUDE.md
 	FormatCopilot    Format = "copilot"    // .github/copilot-instructions.md
@@ -115,7 +115,7 @@ func (e *UnsupportedFormatError) Error() string {
 func formatCandidates(dir string, f Format) []string {
 	switch f {
 	case FormatHawk:
-		return []string{filepath.Join(dir, ".hawk", "rules")}
+		return []string{filepath.Join(dir, ".agents", "rules")}
 	case FormatCursor:
 		return []string{
 			filepath.Join(dir, ".cursor", "rules"),
diff --git a/internal/rules/rules_test.go b/internal/rules/rules_test.go
index cf6f215a..b2652fd8 100644
--- a/internal/rules/rules_test.go
+++ b/internal/rules/rules_test.go
@@ -14,7 +14,7 @@ import (
 
 func TestDetect_HawkRules(t *testing.T) {
 	dir := t.TempDir()
-	rulesDir := filepath.Join(dir, ".hawk", "rules")
+	rulesDir := filepath.Join(dir, ".agents", "rules")
 	must(t, os.MkdirAll(rulesDir, 0o755))
 	must(t, os.WriteFile(filepath.Join(rulesDir, "style.md"), []byte("Use gofmt."), 0o644))
 
@@ -92,7 +92,7 @@ func TestDetect_Multiple(t *testing.T) {
 	dir := t.TempDir()
 
 	// Set up hawk
-	hawkDir := filepath.Join(dir, ".hawk", "rules")
+	hawkDir := filepath.Join(dir, ".agents", "rules")
 	must(t, os.MkdirAll(hawkDir, 0o755))
 	must(t, os.WriteFile(filepath.Join(hawkDir, "a.md"), []byte("rule a"), 0o644))
 
@@ -218,7 +218,7 @@ func TestImport_Gemini(t *testing.T) {
 
 func TestImport_Hawk(t *testing.T) {
 	dir := t.TempDir()
-	rulesDir := filepath.Join(dir, ".hawk", "rules")
+	rulesDir := filepath.Join(dir, ".agents", "rules")
 	must(t, os.MkdirAll(rulesDir, 0o755))
 	must(t, os.WriteFile(filepath.Join(rulesDir, "style.md"), []byte("Use gofmt.\n"), 0o644))
 	must(t, os.WriteFile(filepath.Join(rulesDir, "docs.md"),
@@ -259,7 +259,7 @@ func TestExport_Hawk(t *testing.T) {
 	}
 
 	// Verify files were written.
-	data, err := os.ReadFile(filepath.Join(dir, ".hawk", "rules", "style.md"))
+	data, err := os.ReadFile(filepath.Join(dir, ".agents", "rules", "style.md"))
 	if err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/sandbox/approval.go b/internal/sandbox/approval.go
index 3594adf8..686e3f84 100644
--- a/internal/sandbox/approval.go
+++ b/internal/sandbox/approval.go
@@ -8,6 +8,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // GrantAction represents the action of a grant.
@@ -55,13 +57,12 @@ func NewApprovalStore(filePath string) *ApprovalStore {
 
 // NewProjectApprovalStore creates an approval store for a project directory.
 func NewProjectApprovalStore(projectDir string) *ApprovalStore {
-	return NewApprovalStore(filepath.Join(projectDir, ".hawk", "sandbox.grants.jsonc"))
+	return NewApprovalStore(filepath.Join(storage.ProjectStateDir(projectDir), "sandbox.grants.jsonc"))
 }
 
 // NewGlobalApprovalStore creates an approval store for the user's home directory.
 func NewGlobalApprovalStore() *ApprovalStore {
-	home, _ := os.UserHomeDir()
-	return NewApprovalStore(filepath.Join(home, ".hawk", "sandbox.grants.jsonc"))
+	return NewApprovalStore(filepath.Join(storage.StateDir(), "sandbox.grants.jsonc"))
 }
 
 func (s *ApprovalStore) load() {
diff --git a/internal/sandbox/container.go b/internal/sandbox/container.go
index 170902fd..19e5f475 100644
--- a/internal/sandbox/container.go
+++ b/internal/sandbox/container.go
@@ -10,6 +10,8 @@ import (
 	"strings"
 	"sync"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Compile-time check: ContainerSandbox implements tool.ContainerExecutor.
@@ -69,9 +71,9 @@ func (c *ContainerSandbox) Start(ctx context.Context) error {
 	// Remove any stale container with the same name from a previous session (best-effort)
 	_, _ = exec.CommandContext(ctx, "docker", "rm", "-f", name).CombinedOutput()
 
-	// Create attachments and cache dirs
-	attachDir := filepath.Join(c.projectDir, ".hawk", "attachments")
-	cacheDir := filepath.Join(c.projectDir, ".hawk", "cache")
+	// Create attachments and cache dirs outside the project workspace.
+	attachDir := filepath.Join(storage.ProjectStateDir(c.projectDir), "attachments")
+	cacheDir := filepath.Join(storage.ProjectCacheDir(c.projectDir), "container")
 	_ = os.MkdirAll(attachDir, 0o755)
 	_ = os.MkdirAll(cacheDir, 0o755)
 
@@ -181,7 +183,7 @@ func (c *ContainerSandbox) BuildFromDockerfile(ctx context.Context, dockerfile s
 	hash := sha256.Sum256([]byte(dockerfile))
 	tag := fmt.Sprintf("hawk-sandbox:%x", hash[:6])
 
-	dfPath := filepath.Join(c.projectDir, ".hawk", "Dockerfile")
+	dfPath := filepath.Join(storage.ProjectStateDir(c.projectDir), "Dockerfile")
 	if err := os.MkdirAll(filepath.Dir(dfPath), 0o755); err != nil {
 		return "", err
 	}
@@ -220,7 +222,7 @@ func defaultHawkImage() string {
 }
 
 func resolveImage(projectDir string) string {
-	dfPath := filepath.Join(projectDir, ".hawk", "Dockerfile")
+	dfPath := filepath.Join(storage.ProjectStateDir(projectDir), "Dockerfile")
 	if _, err := os.Stat(dfPath); err == nil {
 		content, err := os.ReadFile(dfPath)
 		if err == nil && len(content) > 0 {
diff --git a/internal/sandbox/container_test.go b/internal/sandbox/container_test.go
index c8514376..43411f1d 100644
--- a/internal/sandbox/container_test.go
+++ b/internal/sandbox/container_test.go
@@ -2,7 +2,10 @@ package sandbox
 
 import (
 	"os"
+	"path/filepath"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 func TestDockerAvailable(t *testing.T) {
@@ -44,11 +47,11 @@ func TestResolveImage_Default(t *testing.T) {
 
 func TestResolveImage_WithDockerfile(t *testing.T) {
 	dir := t.TempDir()
-	hawkDir := dir + "/.hawk"
-	if err := mkdirAll(hawkDir); err != nil {
+	dockerDir := storage.ProjectStateDir(dir)
+	if err := mkdirAll(dockerDir); err != nil {
 		t.Fatal(err)
 	}
-	if err := writeFile(hawkDir+"/Dockerfile", "FROM node:20\nRUN npm install"); err != nil {
+	if err := writeFile(filepath.Join(dockerDir, "Dockerfile"), "FROM node:20\nRUN npm install"); err != nil {
 		t.Fatal(err)
 	}
 	img := resolveImage(dir)
diff --git a/internal/sandbox/manager.go b/internal/sandbox/manager.go
index 4be9f71a..bb06fa52 100644
--- a/internal/sandbox/manager.go
+++ b/internal/sandbox/manager.go
@@ -6,6 +6,8 @@ import (
 	"os"
 	"path/filepath"
 	"sync"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // PolicyDecision represents the outcome of a policy check.
@@ -53,13 +55,10 @@ func NewPolicyManager(projectDir string) *PolicyManager {
 
 func (m *PolicyManager) loadPolicy() {
 	// Load project policy
-	loadPolicyFile(filepath.Join(m.projectDir, ".hawk", "sandbox.jsonc"), m.policy)
+	loadPolicyFile(filepath.Join(m.projectDir, ".agents", "sandbox.jsonc"), m.policy)
 	// Load global policy (overrides defaults but not project)
 	globalPolicy := &PolicyConfig{}
-	home, _ := os.UserHomeDir()
-	if home != "" {
-		loadPolicyFile(filepath.Join(home, ".hawk", "sandbox.jsonc"), globalPolicy)
-	}
+	loadPolicyFile(filepath.Join(storage.StateDir(), "sandbox.jsonc"), globalPolicy)
 	// Project rules take precedence
 	if len(globalPolicy.Rules) > 0 && len(m.policy.Rules) == 0 {
 		m.policy.Rules = globalPolicy.Rules
diff --git a/internal/sandbox/manager_test.go b/internal/sandbox/manager_test.go
index f8dc9ccd..796da6a4 100644
--- a/internal/sandbox/manager_test.go
+++ b/internal/sandbox/manager_test.go
@@ -108,8 +108,8 @@ func TestPolicyManager_CheckTool_DefaultAllow(t *testing.T) {
 
 func TestPolicyManager_CheckTool_DefaultAsk(t *testing.T) {
 	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755)
-	os.WriteFile(filepath.Join(dir, ".hawk", "sandbox.jsonc"), []byte(`{"default": "ask"}`), 0o644)
+	os.MkdirAll(filepath.Join(dir, ".agents"), 0o755)
+	os.WriteFile(filepath.Join(dir, ".agents", "sandbox.jsonc"), []byte(`{"default": "ask"}`), 0o644)
 
 	m := NewPolicyManager(dir)
 
@@ -124,7 +124,7 @@ func TestPolicyManager_CheckTool_DefaultAsk(t *testing.T) {
 
 func TestPolicyManager_CheckTool_PolicyRules(t *testing.T) {
 	dir := t.TempDir()
-	os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755)
+	os.MkdirAll(filepath.Join(dir, ".agents"), 0o755)
 	policy := `{
 		"default": "ask",
 		"rules": [
@@ -132,7 +132,7 @@ func TestPolicyManager_CheckTool_PolicyRules(t *testing.T) {
 			{"class": "write", "pattern": "/etc/*", "action": "deny"}
 		]
 	}`
-	os.WriteFile(filepath.Join(dir, ".hawk", "sandbox.jsonc"), []byte(policy), 0o644)
+	os.WriteFile(filepath.Join(dir, ".agents", "sandbox.jsonc"), []byte(policy), 0o644)
 
 	m := NewPolicyManager(dir)
 
diff --git a/internal/sandbox/mode.go b/internal/sandbox/mode.go
index 9cf76876..7ace390e 100644
--- a/internal/sandbox/mode.go
+++ b/internal/sandbox/mode.go
@@ -4,6 +4,8 @@ import (
 	"context"
 	"os"
 	"path/filepath"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Mode represents the sandbox isolation level.
@@ -63,7 +65,9 @@ func DefaultHawkPolicy(workDir string, tier Tier) *SeatbeltPolicy {
 		gopath = filepath.Join(home, "go")
 	}
 
-	hawkDir := filepath.Join(home, ".hawk")
+	configDir := storage.ConfigDir()
+	stateDir := storage.StateDir()
+	cacheDir := storage.CacheDir()
 
 	readPaths := []string{
 		workDir,
@@ -74,7 +78,9 @@ func DefaultHawkPolicy(workDir string, tier Tier) *SeatbeltPolicy {
 		"/dev",
 		"/tmp",
 		"/private/tmp",
-		hawkDir,
+		configDir,
+		stateDir,
+		cacheDir,
 		gopath,
 	}
 
@@ -83,7 +89,9 @@ func DefaultHawkPolicy(workDir string, tier Tier) *SeatbeltPolicy {
 		"/tmp",
 		"/private/tmp",
 		"/dev/null",
-		hawkDir,
+		configDir,
+		stateDir,
+		cacheDir,
 	}
 
 	p := &SeatbeltPolicy{
diff --git a/internal/sandbox/runtime_deps.go b/internal/sandbox/runtime_deps.go
index c9426fb3..c77334b2 100644
--- a/internal/sandbox/runtime_deps.go
+++ b/internal/sandbox/runtime_deps.go
@@ -9,7 +9,7 @@ import (
 )
 
 // RuntimeConfig declares additive runtime customizations for a container
-// sandbox. It is parsed from .hawk/runtime.jsonc (project) and is fully
+// sandbox. It is parsed from .agents/runtime.jsonc (project) and is fully
 // optional: the empty value reproduces the current behavior exactly.
 type RuntimeConfig struct {
 	// RuntimeExtraDeps is a list of shell commands run during image build,
@@ -26,12 +26,12 @@ func (c RuntimeConfig) IsEmpty() bool {
 	return len(c.RuntimeExtraDeps) == 0 && len(c.RuntimeStartupEnvVars) == 0
 }
 
-// LoadRuntimeConfig reads .hawk/runtime.jsonc from projectDir. A missing file
+// LoadRuntimeConfig reads .agents/runtime.jsonc from projectDir. A missing file
 // yields a zero RuntimeConfig and no error; a malformed file is logged and
 // also yields a zero config (fail-open to current behavior, since this is
 // purely additive).
 func LoadRuntimeConfig(projectDir string) RuntimeConfig {
-	path := filepath.Join(projectDir, ".hawk", "runtime.jsonc")
+	path := filepath.Join(projectDir, ".agents", "runtime.jsonc")
 	data, err := os.ReadFile(path)
 	if err != nil {
 		return RuntimeConfig{}
diff --git a/internal/sandbox/runtime_deps_test.go b/internal/sandbox/runtime_deps_test.go
index 04fad088..3c16bcfe 100644
--- a/internal/sandbox/runtime_deps_test.go
+++ b/internal/sandbox/runtime_deps_test.go
@@ -10,7 +10,7 @@ import (
 
 func TestLoadRuntimeConfig(t *testing.T) {
 	dir := t.TempDir()
-	hawkDir := filepath.Join(dir, ".hawk")
+	hawkDir := filepath.Join(dir, ".agents")
 	if err := os.MkdirAll(hawkDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -44,7 +44,7 @@ func TestLoadRuntimeConfigMissing(t *testing.T) {
 
 func TestLoadRuntimeConfigMalformed(t *testing.T) {
 	dir := t.TempDir()
-	hawkDir := filepath.Join(dir, ".hawk")
+	hawkDir := filepath.Join(dir, ".agents")
 	_ = os.MkdirAll(hawkDir, 0o755)
 	_ = os.WriteFile(filepath.Join(hawkDir, "runtime.jsonc"), []byte("{ not json"), 0o644)
 	cfg := LoadRuntimeConfig(dir)
diff --git a/internal/session/autosave_test.go b/internal/session/autosave_test.go
index 2fd506a0..65a62524 100644
--- a/internal/session/autosave_test.go
+++ b/internal/session/autosave_test.go
@@ -10,7 +10,7 @@ import (
 func TestAcquireLock(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(fmt.Sprintf("%s/.hawk/sessions", dir), 0o755)
+	_ = os.MkdirAll(setTestSessionsDir(t, dir), 0o755)
 
 	lock, err := AcquireLock("test-lock")
 	if err != nil {
@@ -25,7 +25,7 @@ func TestAcquireLock(t *testing.T) {
 func TestAcquireLock_AlreadyLocked(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(fmt.Sprintf("%s/.hawk/sessions", dir), 0o755)
+	_ = os.MkdirAll(setTestSessionsDir(t, dir), 0o755)
 
 	lock1, err := AcquireLock("locked-session")
 	if err != nil {
@@ -49,7 +49,7 @@ func TestAcquireLock_AlreadyLocked(t *testing.T) {
 func TestAcquireLock_StaleLock(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	sessDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	sessDir := setTestSessionsDir(t, dir)
 	_ = os.MkdirAll(sessDir, 0o755)
 
 	// Create a stale lock (>5 min old)
@@ -71,7 +71,7 @@ func TestAcquireLock_StaleLock(t *testing.T) {
 func TestLockFile_Release(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(fmt.Sprintf("%s/.hawk/sessions", dir), 0o755)
+	_ = os.MkdirAll(setTestSessionsDir(t, dir), 0o755)
 
 	lock, _ := AcquireLock("release-test")
 	lock.Release()
@@ -87,7 +87,7 @@ func TestLockFile_Release(t *testing.T) {
 func TestLockFile_Refresh(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(fmt.Sprintf("%s/.hawk/sessions", dir), 0o755)
+	_ = os.MkdirAll(setTestSessionsDir(t, dir), 0o755)
 
 	lock, _ := AcquireLock("refresh-test")
 	defer lock.Release()
@@ -163,7 +163,7 @@ func TestContainsTag(t *testing.T) {
 func TestCleanOldSessions(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	sessDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	sessDir := setTestSessionsDir(t, dir)
 	_ = os.MkdirAll(sessDir, 0o755)
 
 	// Create old sessions
@@ -187,7 +187,7 @@ func TestCleanOldSessions(t *testing.T) {
 func TestExportToMarkdown(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	sessDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	sessDir := setTestSessionsDir(t, dir)
 	_ = os.MkdirAll(sessDir, 0o755)
 
 	sess := &Session{
@@ -211,7 +211,7 @@ func TestExportToMarkdown(t *testing.T) {
 func TestSearchSessions_Integration(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	sessDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	sessDir := setTestSessionsDir(t, dir)
 	_ = os.MkdirAll(sessDir, 0o755)
 
 	sess := &Session{
diff --git a/internal/session/benchmark_test.go b/internal/session/benchmark_test.go
index 1864e89a..4d0f3101 100644
--- a/internal/session/benchmark_test.go
+++ b/internal/session/benchmark_test.go
@@ -3,7 +3,6 @@ package session
 import (
 	"fmt"
 	"os"
-	"path/filepath"
 	"testing"
 	"time"
 )
@@ -178,8 +177,7 @@ func BenchmarkSessionList_50Sessions(b *testing.B) {
 	}
 
 	// Verify files exist.
-	home := os.Getenv("HOME")
-	dir := filepath.Join(home, ".hawk", "sessions")
+	dir := sessionsDir()
 	entries, _ := os.ReadDir(dir)
 	if len(entries) < 50 {
 		b.Fatalf("expected at least 50 session files, got %d", len(entries))
diff --git a/internal/session/export_redact_test.go b/internal/session/export_redact_test.go
index d6186b9a..9325a987 100644
--- a/internal/session/export_redact_test.go
+++ b/internal/session/export_redact_test.go
@@ -36,7 +36,7 @@ func TestRedactSessionMessages(t *testing.T) {
 func TestExport_JSON(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk/sessions", 0o755)
+	_ = os.MkdirAll(setTestSessionsDir(t, dir), 0o755)
 
 	sess := &Session{
 		ID: "export-json", Model: "test", CreatedAt: time.Now(), UpdatedAt: time.Now(),
@@ -56,7 +56,7 @@ func TestExport_JSON(t *testing.T) {
 func TestExport_Markdown(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk/sessions", 0o755)
+	_ = os.MkdirAll(setTestSessionsDir(t, dir), 0o755)
 
 	sess := &Session{
 		ID: "export-md", Model: "test", CreatedAt: time.Now(), UpdatedAt: time.Now(),
diff --git a/internal/session/persist.go b/internal/session/persist.go
index a004fbb4..5edb4aa5 100644
--- a/internal/session/persist.go
+++ b/internal/session/persist.go
@@ -5,6 +5,8 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // SaveMessages serializes a slice of conversation messages to a JSON file
@@ -64,7 +66,7 @@ func LoadMessages(path string) ([]Message, error) {
 }
 
 // SessionPath returns the file path for a session within a project directory.
-// Sessions are stored under .hawk/sessions/{id}.json.
+// Sessions are stored under the user state directory, partitioned by project.
 func SessionPath(projectDir, sessionID string) string {
-	return filepath.Join(projectDir, ".hawk", "sessions", sessionID+".json")
+	return filepath.Join(storage.ProjectStateDir(projectDir), "sessions", sessionID+".json")
 }
diff --git a/internal/session/persist_integrity_test.go b/internal/session/persist_integrity_test.go
index d84d779c..416682f6 100644
--- a/internal/session/persist_integrity_test.go
+++ b/internal/session/persist_integrity_test.go
@@ -1,8 +1,8 @@
 package session
 
 import (
-	"fmt"
-	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 )
@@ -10,7 +10,6 @@ import (
 func TestSaveAndLoadMessages(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(fmt.Sprintf("%s/.hawk/sessions", dir), 0o755)
 
 	msgs := []Message{
 		{Role: "user", Content: "hello"},
@@ -34,11 +33,19 @@ func TestSaveAndLoadMessages(t *testing.T) {
 func TestSessionPath(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
+	stateDir := filepath.Join(dir, "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
 
 	path := SessionPath(dir, "test-id")
 	if path == "" {
 		t.Error("SessionPath should return non-empty")
 	}
+	if strings.Contains(path, ".hawk") {
+		t.Fatalf("SessionPath() leaked project .hawk path: %q", path)
+	}
+	if !strings.HasPrefix(path, stateDir) {
+		t.Fatalf("SessionPath() = %q, want under %q", path, stateDir)
+	}
 }
 
 func TestValidateIntegrity(t *testing.T) {
@@ -79,7 +86,7 @@ func TestStats(t *testing.T) {
 func TestLoadLatest(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(fmt.Sprintf("%s/.hawk/sessions", dir), 0o755)
+	t.Setenv("HAWK_STATE_DIR", filepath.Join(dir, "state"))
 
 	sess := &Session{
 		ID: "latest-test", Model: "test", CWD: dir, CreatedAt: time.Now(), UpdatedAt: time.Now(),
diff --git a/internal/session/session.go b/internal/session/session.go
index 475830b6..6202d20b 100644
--- a/internal/session/session.go
+++ b/internal/session/session.go
@@ -10,7 +10,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/GrayCodeAI/hawk/internal/types"
 )
 
@@ -41,8 +41,7 @@ type Session struct {
 }
 
 func sessionsDir() string {
-	home := home.Dir()
-	return filepath.Join(home, ".hawk", "sessions")
+	return storage.SessionsDir()
 }
 
 func legacyPathFor(id string) string {
@@ -321,12 +320,17 @@ func Load(id string) (*Session, error) {
 	if s, err := loadJSONL(id); err == nil {
 		return s, nil
 	}
-	// Fall back to legacy JSON
-	return loadLegacyJSON(id)
+	if s, err := loadLegacyJSON(id); err == nil {
+		return s, nil
+	}
+	return nil, fmt.Errorf("session %s not found", id)
 }
 
 func loadJSONL(id string) (*Session, error) {
-	path := jsonlPathFor(id)
+	return loadJSONLFile(jsonlPathFor(id), id)
+}
+
+func loadJSONLFile(path, id string) (*Session, error) {
 	f, err := os.Open(path)
 	if err != nil {
 		return nil, err
@@ -387,10 +391,13 @@ func loadJSONL(id string) (*Session, error) {
 }
 
 func loadLegacyJSON(id string) (*Session, error) {
-	path := legacyPathFor(id)
+	return loadLegacyJSONFile(legacyPathFor(id))
+}
+
+func loadLegacyJSONFile(path string) (*Session, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
-		return nil, fmt.Errorf("session %s not found", id)
+		return nil, err
 	}
 	var s Session
 	if err := json.Unmarshal(data, &s); err != nil {
diff --git a/internal/session/session_concurrent_test.go b/internal/session/session_concurrent_test.go
index d7f7a2fc..a6d6e5f8 100644
--- a/internal/session/session_concurrent_test.go
+++ b/internal/session/session_concurrent_test.go
@@ -12,7 +12,7 @@ func TestWAL_ConcurrentAppend(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
 
-	hawkDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	hawkDir := setTestSessionsDir(t, dir)
 	if err := os.MkdirAll(hawkDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -44,7 +44,7 @@ func TestSession_ConcurrentSaveLoad(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
 
-	hawkDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	hawkDir := setTestSessionsDir(t, dir)
 	if err := os.MkdirAll(hawkDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
@@ -87,7 +87,7 @@ func TestSession_ConcurrentList(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
 
-	hawkDir := fmt.Sprintf("%s/.hawk/sessions", dir)
+	hawkDir := setTestSessionsDir(t, dir)
 	if err := os.MkdirAll(hawkDir, 0o755); err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/session/session_safety_test.go b/internal/session/session_safety_test.go
index eb90e0f2..26e5bc24 100644
--- a/internal/session/session_safety_test.go
+++ b/internal/session/session_safety_test.go
@@ -13,6 +13,7 @@ func TestAtomicSave(t *testing.T) {
 	origHome := os.Getenv("HOME")
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
+	sessDir := setTestSessionsDir(t, tmp)
 
 	sess := &Session{
 		ID:       "test-atomic-1",
@@ -32,7 +33,7 @@ func TestAtomicSave(t *testing.T) {
 	}
 
 	// File should exist (no .tmp leftover)
-	path := filepath.Join(tmp, ".hawk", "sessions", "test-atomic-1.jsonl")
+	path := filepath.Join(sessDir, "test-atomic-1.jsonl")
 	if _, err := os.Stat(path); err != nil {
 		t.Fatalf("session file not found: %v", err)
 	}
@@ -61,6 +62,7 @@ func TestAtomicSave_OverwritesCleanly(t *testing.T) {
 	origHome := os.Getenv("HOME")
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
+	setTestSessionsDir(t, tmp)
 
 	sess := &Session{
 		ID:       "test-overwrite",
@@ -89,7 +91,7 @@ func TestWAL_BasicAppend(t *testing.T) {
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
 
-	os.MkdirAll(filepath.Join(tmp, ".hawk", "sessions"), 0o755)
+	os.MkdirAll(setTestSessionsDir(t, tmp), 0o755)
 
 	wal, err := NewWAL("test-wal-1")
 	if err != nil {
@@ -128,14 +130,15 @@ func TestWAL_Remove(t *testing.T) {
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
 
-	os.MkdirAll(filepath.Join(tmp, ".hawk", "sessions"), 0o755)
+	sessDir := setTestSessionsDir(t, tmp)
+	os.MkdirAll(sessDir, 0o755)
 
 	wal, _ := NewWAL("test-wal-remove")
 	wal.Append(Message{Role: "user", Content: "test"})
 	wal.Remove()
 
 	// WAL file should be gone
-	path := filepath.Join(tmp, ".hawk", "sessions", "test-wal-remove.wal")
+	path := filepath.Join(sessDir, "test-wal-remove.wal")
 	if _, err := os.Stat(path); err == nil {
 		t.Error("WAL file should be removed")
 	}
@@ -152,6 +155,7 @@ func TestWAL_NoRecoveryIfNoWAL(t *testing.T) {
 	origHome := os.Getenv("HOME")
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
+	setTestSessionsDir(t, tmp)
 
 	recovered, err := RecoverFromWAL("nonexistent")
 	if err != nil {
@@ -168,7 +172,7 @@ func TestCheckForRecovery(t *testing.T) {
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
 
-	dir := filepath.Join(tmp, ".hawk", "sessions")
+	dir := setTestSessionsDir(t, tmp)
 	os.MkdirAll(dir, 0o755)
 
 	// Create some WAL files
@@ -204,7 +208,7 @@ func TestList_UsesFileModTime(t *testing.T) {
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
 
-	dir := filepath.Join(tmp, ".hawk", "sessions")
+	dir := setTestSessionsDir(t, tmp)
 	os.MkdirAll(dir, 0o755)
 
 	// Create two session files with different mod times
@@ -237,7 +241,7 @@ func TestCorruptedLineSkipped(t *testing.T) {
 	os.Setenv("HOME", tmp)
 	defer os.Setenv("HOME", origHome)
 
-	dir := filepath.Join(tmp, ".hawk", "sessions")
+	dir := setTestSessionsDir(t, tmp)
 	os.MkdirAll(dir, 0o755)
 
 	// Write a file with one corrupted line
diff --git a/internal/session/snapshot.go b/internal/session/snapshot.go
index 87c1d232..2480327a 100644
--- a/internal/session/snapshot.go
+++ b/internal/session/snapshot.go
@@ -8,7 +8,7 @@ import (
 	"sort"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Snapshot records a point-in-time copy of a session.
@@ -30,8 +30,7 @@ type SnapshotStore struct {
 
 // NewSnapshotStore creates a new snapshot store for the given session.
 func NewSnapshotStore(sessionID string) *SnapshotStore {
-	home := home.Dir()
-	dir := filepath.Join(home, ".hawk", "sessions", sessionID, "snapshots")
+	dir := filepath.Join(storage.SessionsDir(), sessionID, "snapshots")
 	return &SnapshotStore{
 		sessionID: sessionID,
 		dir:       dir,
diff --git a/internal/session/storage_policy_test.go b/internal/session/storage_policy_test.go
new file mode 100644
index 00000000..ee8da9a6
--- /dev/null
+++ b/internal/session/storage_policy_test.go
@@ -0,0 +1,25 @@
+package session
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestSessionPathDoesNotCreateProjectHawk(t *testing.T) {
+	project := t.TempDir()
+	state := filepath.Join(t.TempDir(), "state")
+	t.Setenv("HAWK_STATE_DIR", state)
+
+	path := SessionPath(project, "abc123")
+	if strings.Contains(path, filepath.Join(project, ".hawk")) {
+		t.Fatalf("SessionPath leaked project .hawk: %q", path)
+	}
+	if !strings.HasPrefix(path, state) {
+		t.Fatalf("SessionPath = %q, want under %q", path, state)
+	}
+	if _, err := os.Stat(filepath.Join(project, ".hawk")); !os.IsNotExist(err) {
+		t.Fatalf("SessionPath created project .hawk, stat err=%v", err)
+	}
+}
diff --git a/internal/session/storage_test_helpers_test.go b/internal/session/storage_test_helpers_test.go
new file mode 100644
index 00000000..b8b1245e
--- /dev/null
+++ b/internal/session/storage_test_helpers_test.go
@@ -0,0 +1,13 @@
+package session
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+func setTestSessionsDir(t *testing.T, root string) string {
+	t.Helper()
+	stateDir := filepath.Join(root, "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
+	return filepath.Join(stateDir, "sessions")
+}
diff --git a/internal/snapshot/snapshot.go b/internal/snapshot/snapshot.go
index 30e92979..d8d80323 100644
--- a/internal/snapshot/snapshot.go
+++ b/internal/snapshot/snapshot.go
@@ -10,7 +10,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // Tracker maintains a shadow git repository that records every file change
@@ -38,13 +38,13 @@ type FileDiff struct {
 }
 
 // New creates a Tracker for the given project directory.
-// The shadow git repository lives under the user's home dir (~/.hawk/snapshots)
+// The shadow git repository lives under Hawk's user state snapshots directory
 // rather than under projectDir, so that running hawk from inside a Go project
 // root no longer creates a nested <cwd>/cmd/.hawk/ tree at runtime.
 func New(projectDir string) *Tracker {
 	return &Tracker{
 		projectDir: projectDir,
-		shadowDir:  filepath.Join(home.Dir(), ".hawk", "snapshots"),
+		shadowDir:  storage.WorkspaceSnapshotsDir(),
 	}
 }
 
diff --git a/internal/snapshot/workspace.go b/internal/snapshot/workspace.go
index b3d2605b..ea9466c9 100644
--- a/internal/snapshot/workspace.go
+++ b/internal/snapshot/workspace.go
@@ -17,7 +17,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // WorkspaceSnapshot captures the full state of a project at a point in time.
@@ -70,12 +70,12 @@ var ignoredDirs = map[string]bool{
 }
 
 // NewSnapshotStore creates a new SnapshotStore with the given directory.
-// If dir is empty, defaults to "~/.hawk/snapshots" (the user's home dir) so
+// If dir is empty, defaults to Hawk's user state snapshots directory so
 // that state does not leak into <cwd>/.hawk/ when hawk is run from inside
 // a Go project root.
 func NewSnapshotStore(dir string) *SnapshotStore {
 	if dir == "" {
-		dir = filepath.Join(home.Dir(), ".hawk", "snapshots")
+		dir = storage.WorkspaceSnapshotsDir()
 	}
 	return &SnapshotStore{
 		Dir:          dir,
diff --git a/internal/snapshot/workspace_test.go b/internal/snapshot/workspace_test.go
index 9cf33114..53318957 100644
--- a/internal/snapshot/workspace_test.go
+++ b/internal/snapshot/workspace_test.go
@@ -601,15 +601,14 @@ func TestRestore_PreservesGitDir(t *testing.T) {
 }
 
 func TestNewSnapshotStore_DefaultDir(t *testing.T) {
+	stateDir := filepath.Join(t.TempDir(), "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
+
 	store := NewSnapshotStore("")
-	// L2: the default path is now home-relative (~/.hawk/snapshots) so
+	// L2: the default path is now user-state-relative so
 	// state stops leaking into <cwd>/.hawk/ when hawk is run from
 	// inside a Go project root.
-	home, err := os.UserHomeDir()
-	if err != nil {
-		t.Fatalf("os.UserHomeDir: %v", err)
-	}
-	expected := filepath.Join(home, ".hawk", "snapshots")
+	expected := filepath.Join(stateDir, "snapshots")
 	if store.Dir != expected {
 		t.Errorf("expected default dir %q, got %q", expected, store.Dir)
 	}
diff --git a/internal/storage/paths.go b/internal/storage/paths.go
new file mode 100644
index 00000000..70583093
--- /dev/null
+++ b/internal/storage/paths.go
@@ -0,0 +1,147 @@
+package storage
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const (
+	appName          = "hawk"
+	envConfigDir     = "HAWK_CONFIG_DIR"
+	envStateDir      = "HAWK_STATE_DIR"
+	envCacheDir      = "HAWK_CACHE_DIR"
+	projectIDHashLen = 12
+)
+
+// ConfigDir returns the per-user configuration directory for Hawk.
+func ConfigDir() string {
+	if dir := cleanEnvDir(envConfigDir); dir != "" {
+		return dir
+	}
+	return filepath.Join(mustUserConfigDir(), appName)
+}
+
+// StateDir returns the per-user state directory for durable runtime data.
+func StateDir() string {
+	if dir := cleanEnvDir(envStateDir); dir != "" {
+		return dir
+	}
+	if dir := cleanEnvDir("XDG_STATE_HOME"); dir != "" {
+		return filepath.Join(dir, appName)
+	}
+	return filepath.Join(mustUserConfigDir(), appName, "state")
+}
+
+// CacheDir returns the per-user cache directory for disposable data.
+func CacheDir() string {
+	if dir := cleanEnvDir(envCacheDir); dir != "" {
+		return dir
+	}
+	return filepath.Join(mustUserCacheDir(), appName)
+}
+
+func SettingsPath() string {
+	return filepath.Join(ConfigDir(), "settings.json")
+}
+
+func ProviderConfigPath() string {
+	return filepath.Join(ConfigDir(), "provider.json")
+}
+
+func SessionsDir() string {
+	return filepath.Join(StateDir(), "sessions")
+}
+
+func PlansDir(projectRoot string) string {
+	return filepath.Join(ProjectStateDir(projectRoot), "plans")
+}
+
+func DaemonRunDir() string {
+	return filepath.Join(StateDir(), "run")
+}
+
+func WorkspaceSnapshotsDir() string {
+	return filepath.Join(StateDir(), "snapshots")
+}
+
+func BundledSkillsDir() string {
+	return filepath.Join(StateDir(), "bundled-skills")
+}
+
+func PersonasDir() string {
+	return filepath.Join(StateDir(), "agents")
+}
+
+func TasteDir() string {
+	return filepath.Join(StateDir(), "taste")
+}
+
+func RepoMapCacheDir(projectRoot string) string {
+	return filepath.Join(ProjectCacheDir(projectRoot), "repomap")
+}
+
+func ProjectStateDir(projectRoot string) string {
+	return filepath.Join(StateDir(), "projects", ProjectID(projectRoot))
+}
+
+func ProjectCacheDir(projectRoot string) string {
+	return filepath.Join(CacheDir(), "projects", ProjectID(projectRoot))
+}
+
+// ProjectID returns a stable, filesystem-safe identifier for a project path.
+func ProjectID(projectRoot string) string {
+	if projectRoot == "" {
+		projectRoot = "."
+	}
+	abs, err := filepath.Abs(projectRoot)
+	if err == nil {
+		projectRoot = abs
+	}
+	projectRoot = filepath.Clean(projectRoot)
+	base := filepath.Base(projectRoot)
+	if base == "." || base == string(filepath.Separator) || base == "" {
+		base = "project"
+	}
+	base = sanitizeName(base)
+	sum := sha256.Sum256([]byte(projectRoot))
+	return base + "-" + hex.EncodeToString(sum[:])[:projectIDHashLen]
+}
+
+func cleanEnvDir(key string) string {
+	return strings.TrimSpace(os.Getenv(key))
+}
+
+func mustUserConfigDir() string {
+	dir, err := os.UserConfigDir()
+	if err != nil || dir == "" {
+		panic("hawk storage: user config directory unavailable")
+	}
+	return dir
+}
+
+func mustUserCacheDir() string {
+	dir, err := os.UserCacheDir()
+	if err != nil || dir == "" {
+		panic("hawk storage: user cache directory unavailable")
+	}
+	return dir
+}
+
+func sanitizeName(name string) string {
+	var b strings.Builder
+	for _, r := range name {
+		if r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' || r == '-' || r == '_' || r == '.' {
+			b.WriteRune(r)
+			continue
+		}
+		b.WriteByte('-')
+	}
+	out := strings.Trim(b.String(), ".-")
+	if out == "" {
+		return "project"
+	}
+	return out
+}
diff --git a/internal/storage/paths_test.go b/internal/storage/paths_test.go
new file mode 100644
index 00000000..488994e5
--- /dev/null
+++ b/internal/storage/paths_test.go
@@ -0,0 +1,58 @@
+package storage
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestStorageDirsRespectOverrides(t *testing.T) {
+	configDir := filepath.Join(t.TempDir(), "cfg")
+	stateDir := filepath.Join(t.TempDir(), "state")
+	cacheDir := filepath.Join(t.TempDir(), "cache")
+	t.Setenv(envConfigDir, configDir)
+	t.Setenv(envStateDir, stateDir)
+	t.Setenv(envCacheDir, cacheDir)
+
+	if got := ConfigDir(); got != configDir {
+		t.Fatalf("ConfigDir() = %q, want override %q", got, configDir)
+	}
+	if got := StateDir(); got != stateDir {
+		t.Fatalf("StateDir() = %q, want override %q", got, stateDir)
+	}
+	if got := CacheDir(); got != cacheDir {
+		t.Fatalf("CacheDir() = %q, want override %q", got, cacheDir)
+	}
+}
+
+func TestProjectIDIsStableAndSafe(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "my project")
+
+	first := ProjectID(root)
+	second := ProjectID(root)
+	if first != second {
+		t.Fatalf("ProjectID not stable: %q != %q", first, second)
+	}
+	if !strings.HasPrefix(first, "my-project-") {
+		t.Fatalf("ProjectID() = %q, want sanitized base prefix", first)
+	}
+	if strings.ContainsAny(first, string(filepath.Separator)+" ") {
+		t.Fatalf("ProjectID() = %q, contains unsafe path characters", first)
+	}
+}
+
+func TestProjectStateAndCacheUseHashedProjectRoot(t *testing.T) {
+	state := filepath.Join(t.TempDir(), "state")
+	cache := filepath.Join(t.TempDir(), "cache")
+	project := filepath.Join(t.TempDir(), "repo")
+	t.Setenv(envStateDir, state)
+	t.Setenv(envCacheDir, cache)
+
+	id := ProjectID(project)
+	if got := ProjectStateDir(project); got != filepath.Join(state, "projects", id) {
+		t.Fatalf("ProjectStateDir() = %q", got)
+	}
+	if got := ProjectCacheDir(project); got != filepath.Join(cache, "projects", id) {
+		t.Fatalf("ProjectCacheDir() = %q", got)
+	}
+}
diff --git a/internal/tool/audit.go b/internal/tool/audit.go
index d748d37c..95076e79 100644
--- a/internal/tool/audit.go
+++ b/internal/tool/audit.go
@@ -8,7 +8,7 @@ import (
 	"sync"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // AuditEntry records a file modification event.
@@ -37,8 +37,7 @@ var (
 // GetAuditLog returns the global audit log instance.
 func GetAuditLog() *AuditLog {
 	auditOnce.Do(func() {
-		home := home.Dir()
-		dir := filepath.Join(home, ".hawk", "audit")
+		dir := filepath.Join(storage.StateDir(), "audit")
 		_ = os.MkdirAll(dir, 0o755)
 
 		today := time.Now().Format("2006-01-02")
@@ -110,9 +109,8 @@ func RecordFileDelete(toolName, path string) {
 
 // TodayEntries reads today's audit entries.
 func TodayEntries() ([]AuditEntry, error) {
-	home := home.Dir()
 	today := time.Now().Format("2006-01-02")
-	path := filepath.Join(home, ".hawk", "audit", today+".jsonl")
+	path := filepath.Join(storage.StateDir(), "audit", today+".jsonl")
 
 	data, err := os.ReadFile(path)
 	if err != nil {
diff --git a/internal/tool/backup.go b/internal/tool/backup.go
index a7cd890e..bf0d65f0 100644
--- a/internal/tool/backup.go
+++ b/internal/tool/backup.go
@@ -7,7 +7,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // BackupFile creates a backup of a file before modification.
@@ -110,8 +110,7 @@ func ListBackups(path string) []string {
 // UndoLatest finds the most recent backup across all files and restores it.
 // Returns the restored file path for display, or an error if no backups exist.
 func UndoLatest() (string, error) {
-	home := home.Dir()
-	backupsRoot := filepath.Join(home, ".hawk", "backups")
+	backupsRoot := filepath.Join(storage.StateDir(), "backups")
 	dirs, err := os.ReadDir(backupsRoot)
 	if err != nil {
 		return "", fmt.Errorf("no file changes to undo")
@@ -168,7 +167,6 @@ func UndoLatest() (string, error) {
 }
 
 func backupDirFor(path string) string {
-	home := home.Dir()
 	absPath, err := filepath.Abs(path)
 	if err != nil {
 		absPath = path
@@ -176,7 +174,7 @@ func backupDirFor(path string) string {
 	// Hash the directory to create a unique backup subdir
 	dir := filepath.Dir(absPath)
 	hash := simpleHash(dir)
-	return filepath.Join(home, ".hawk", "backups", hash)
+	return filepath.Join(storage.StateDir(), "backups", hash)
 }
 
 func simpleHash(s string) string {
diff --git a/internal/tool/devenv.go b/internal/tool/devenv.go
index e499d966..94ff9d30 100644
--- a/internal/tool/devenv.go
+++ b/internal/tool/devenv.go
@@ -9,6 +9,7 @@ import (
 	"strings"
 
 	"github.com/GrayCodeAI/hawk/internal/sandbox"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // DevEnvTool allows the agent to read, write, and build Docker environments
@@ -55,14 +56,14 @@ func (t DevEnvTool) Execute(ctx context.Context, input json.RawMessage) (string,
 	}
 
 	workDir, _ := os.Getwd()
-	dfPath := filepath.Join(workDir, ".hawk", "Dockerfile")
+	dfPath := filepath.Join(storage.ProjectStateDir(workDir), "Dockerfile")
 
 	switch p.Action {
 	case "read":
 		content, err := os.ReadFile(dfPath)
 		if err != nil {
 			if os.IsNotExist(err) {
-				return "No Dockerfile found at .hawk/Dockerfile. Use action='write' to create one.", nil
+				return "No Hawk dev environment Dockerfile found. Use action='write' to create one in Hawk user state.", nil
 			}
 			return "", err
 		}
diff --git a/internal/tool/safety.go b/internal/tool/safety.go
index e1c28745..066cb96d 100644
--- a/internal/tool/safety.go
+++ b/internal/tool/safety.go
@@ -13,6 +13,7 @@ import (
 
 	"github.com/GrayCodeAI/hawk/internal/env"
 	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 // ──────────────────────────────────────────────────────────────────────────────
@@ -267,6 +268,11 @@ func IsSensitivePath(path string) string {
 		}
 	}
 
+	providerPath := filepath.Clean(storage.ProviderConfigPath())
+	if clean == providerPath {
+		return "access to provider.json is blocked for security (API credentials)"
+	}
+
 	if cfgDir := strings.TrimSpace(env.Getenv("HAWK_CONFIG_DIR")); cfgDir != "" {
 		customProv := filepath.Clean(filepath.Join(cfgDir, "provider.json"))
 		if clean == customProv {
diff --git a/internal/tool/skill.go b/internal/tool/skill.go
index 1175cfee..e05d596f 100644
--- a/internal/tool/skill.go
+++ b/internal/tool/skill.go
@@ -8,6 +8,8 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 type SkillTool struct{}
@@ -39,7 +41,7 @@ func (SkillTool) Execute(_ context.Context, input json.RawMessage) (string, erro
 	skills := discoverSkills()
 	if p.Skill == "" {
 		if len(skills) == 0 {
-			return "No skills found in .hawk/skills, ~/.hawk/skills, or .codex/skills.", nil
+			return "No skills found in Hawk user state, .agents/skills, or .codex/skills.", nil
 		}
 		names := make([]string, 0, len(skills))
 		for name := range skills {
@@ -90,13 +92,20 @@ func discoverSkills() map[string]string {
 
 func skillRoots() []string {
 	var roots []string
+	roots = append(roots, filepath.Join(storage.StateDir(), "skills"))
 	if cwd, err := os.Getwd(); err == nil {
-		roots = append(roots, filepath.Join(cwd, ".hawk", "skills"))
+		roots = append(
+			roots,
+			filepath.Join(cwd, ".agents", "skills"),
+			filepath.Join(cwd, ".claude", "skills"),
+			filepath.Join(cwd, ".codex", "skills"),
+		)
 	}
 	if home, err := os.UserHomeDir(); err == nil {
 		roots = append(
 			roots,
-			filepath.Join(home, ".hawk", "skills"),
+			filepath.Join(home, ".agents", "skills"),
+			filepath.Join(home, ".claude", "skills"),
 			filepath.Join(home, ".codex", "skills"),
 		)
 	}
diff --git a/internal/tool/tool_test.go b/internal/tool/tool_test.go
index 27473e35..e15469fe 100644
--- a/internal/tool/tool_test.go
+++ b/internal/tool/tool_test.go
@@ -377,7 +377,9 @@ func TestConfigToolGetsAndSetsSupportedSettings(t *testing.T) {
 func TestSkillToolListsAndReadsSkills(t *testing.T) {
 	home := t.TempDir()
 	t.Setenv("HOME", home)
-	dir := filepath.Join(home, ".hawk", "skills", "review")
+	stateDir := filepath.Join(home, "state")
+	t.Setenv("HAWK_STATE_DIR", stateDir)
+	dir := filepath.Join(stateDir, "skills", "review")
 	if err := os.MkdirAll(dir, 0o755); err != nil {
 		t.Fatal(err)
 	}
diff --git a/internal/tool/treesitter.go b/internal/tool/treesitter.go
index 11bdb538..62c51e7a 100644
--- a/internal/tool/treesitter.go
+++ b/internal/tool/treesitter.go
@@ -7,6 +7,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"github.com/tetratelabs/wazero"
 	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
 )
@@ -20,8 +21,7 @@ type TreeSitter struct {
 // NewTreeSitter creates a TreeSitter instance that loads grammars from the given directory.
 func NewTreeSitter(grammarDir string) *TreeSitter {
 	if grammarDir == "" {
-		home, _ := os.UserHomeDir()
-		grammarDir = filepath.Join(home, ".hawk", "grammars")
+		grammarDir = filepath.Join(storage.CacheDir(), "grammars")
 	}
 	return &TreeSitter{grammarDir: grammarDir}
 }
diff --git a/internal/tool/workflow.go b/internal/tool/workflow.go
index caae1783..23199122 100644
--- a/internal/tool/workflow.go
+++ b/internal/tool/workflow.go
@@ -8,11 +8,11 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/GrayCodeAI/hawk/internal/home"
+	"github.com/GrayCodeAI/hawk/internal/storage"
 	"gopkg.in/yaml.v3"
 )
 
-// WorkflowDef defines a scripted workflow loaded from .hawk/workflows/.
+// WorkflowDef defines a scripted workflow.
 type WorkflowDef struct {
 	Name        string         `yaml:"name" json:"name"`
 	Description string         `yaml:"description" json:"description"`
@@ -28,13 +28,13 @@ type WorkflowStep struct {
 	OnError string `yaml:"on_error" json:"on_error"`
 }
 
-// WorkflowTool executes scripted workflows from .hawk/workflows/.
+// WorkflowTool executes scripted workflows.
 type WorkflowTool struct{}
 
 func (WorkflowTool) Name() string      { return "Workflow" }
 func (WorkflowTool) Aliases() []string { return []string{"workflow"} }
 func (WorkflowTool) Description() string {
-	return "Execute a scripted workflow defined in .hawk/workflows/"
+	return "Execute a scripted workflow"
 }
 
 func (WorkflowTool) Parameters() map[string]interface{} {
@@ -43,7 +43,7 @@ func (WorkflowTool) Parameters() map[string]interface{} {
 		"properties": map[string]interface{}{
 			"workflow": map[string]interface{}{
 				"type":        "string",
-				"description": "Name of the workflow to execute (from .hawk/workflows/)",
+				"description": "Name of the workflow to execute",
 			},
 			"args": map[string]interface{}{
 				"type":        "object",
@@ -96,19 +96,11 @@ func (WorkflowTool) Execute(ctx context.Context, input json.RawMessage) (string,
 }
 
 func loadWorkflow(name string) (*WorkflowDef, error) {
-	// Search in .hawk/workflows/ relative to cwd, then home
 	searchPaths := []string{
-		filepath.Join(".hawk", "workflows", name+".yml"),
-		filepath.Join(".hawk", "workflows", name+".yaml"),
-	}
-
-	home := home.Dir()
-	if home != "" {
-		searchPaths = append(
-			searchPaths,
-			filepath.Join(home, ".hawk", "workflows", name+".yml"),
-			filepath.Join(home, ".hawk", "workflows", name+".yaml"),
-		)
+		filepath.Join(storage.StateDir(), "workflows", name+".yml"),
+		filepath.Join(storage.StateDir(), "workflows", name+".yaml"),
+		filepath.Join(".agents", "workflows", name+".yml"),
+		filepath.Join(".agents", "workflows", name+".yaml"),
 	}
 
 	for _, path := range searchPaths {
@@ -125,17 +117,13 @@ func loadWorkflow(name string) (*WorkflowDef, error) {
 		}
 		return &def, nil
 	}
-	return nil, fmt.Errorf("workflow %q not found in .hawk/workflows/", name)
+	return nil, fmt.Errorf("workflow %q not found", name)
 }
 
 // ListWorkflows discovers available workflows.
 func ListWorkflows() []WorkflowDef {
 	var workflows []WorkflowDef
-	searchDirs := []string{filepath.Join(".hawk", "workflows")}
-	home := home.Dir()
-	if home != "" {
-		searchDirs = append(searchDirs, filepath.Join(home, ".hawk", "workflows"))
-	}
+	searchDirs := []string{filepath.Join(storage.StateDir(), "workflows"), filepath.Join(".agents", "workflows")}
 
 	seen := make(map[string]bool)
 	for _, dir := range searchDirs {
diff --git a/lefthook.yml b/lefthook.yml
index 0755c8ee..af2148cf 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -46,7 +46,7 @@ pre-commit:
           echo "lefthook: golangci-lint not installed — skipping (install: https://golangci-lint.run/usage/install/)"
           exit 0
         fi
-        golangci-lint run --new-from-rev=HEAD~1 --fix {staged_files}
+        golangci-lint run --new-from-rev=HEAD~1 --fix ./...
       stage_fixed: true
 
     ast-grep:

From 8bfd07014cfc7adf0f3b54a0ed5b028b8e8017da Mon Sep 17 00:00:00 2001
From: Lakshman Patel <Lakshmanp230@gmail.com>
Date: Sat, 20 Jun 2026 10:52:52 +0530
Subject: [PATCH 2/3] fix(test): isolate storage dirs in race-sensitive tests

Tests that only set HOME were reading real CI state after the storage
policy refactor. Route them through HAWK_* dir overrides and bump eyrie.
---
 external/eyrie                                |  2 +-
 internal/intelligence/memory/memory_test.go   | 58 ++++++++++---------
 internal/observability/analytics_test.go      | 19 ++++--
 internal/session/named_checkpoint_test.go     |  8 +--
 internal/session/storage_test_helpers_test.go |  8 +--
 internal/storage/testdirs.go                  | 14 +++++
 6 files changed, 68 insertions(+), 41 deletions(-)
 create mode 100644 internal/storage/testdirs.go

diff --git a/external/eyrie b/external/eyrie
index a3547d9e..9c736018 160000
--- a/external/eyrie
+++ b/external/eyrie
@@ -1 +1 @@
-Subproject commit a3547d9e481002564f0e253c3ded56c21877c4d0
+Subproject commit 9c736018d8a8a4c01e7832e08bf77836a3d21cc8
diff --git a/internal/intelligence/memory/memory_test.go b/internal/intelligence/memory/memory_test.go
index 6a6da7e1..ce9b5d2d 100644
--- a/internal/intelligence/memory/memory_test.go
+++ b/internal/intelligence/memory/memory_test.go
@@ -2,15 +2,21 @@ package memory
 
 import (
 	"fmt"
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
-func TestSaveAndLoad(t *testing.T) {
+func setTestStorage(t *testing.T) {
+	t.Helper()
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
+	storage.SetTestDirs(t, dir)
+}
+
+func TestSaveAndLoad(t *testing.T) {
+	setTestStorage(t)
 
 	m := &Memory{
 		Content: "Important decision about architecture",
@@ -40,8 +46,7 @@ func TestSaveAndLoad(t *testing.T) {
 }
 
 func TestSave_SetsDefaults(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	m := &Memory{Content: "test"}
 	if err := Save(m); err != nil {
@@ -56,8 +61,7 @@ func TestSave_SetsDefaults(t *testing.T) {
 }
 
 func TestSave_PreservesExistingID(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	m := &Memory{ID: "custom-id", Content: "test"}
 	if err := Save(m); err != nil {
@@ -69,8 +73,7 @@ func TestSave_PreservesExistingID(t *testing.T) {
 }
 
 func TestLoad_NotFound(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	_, err := Load("nonexistent")
 	if err == nil {
@@ -79,8 +82,7 @@ func TestLoad_NotFound(t *testing.T) {
 }
 
 func TestList_Empty(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	memories, err := List()
 	if err != nil {
@@ -92,8 +94,7 @@ func TestList_Empty(t *testing.T) {
 }
 
 func TestList_Multiple(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	for i := 0; i < 5; i++ {
 		m := &Memory{ID: fmt.Sprintf("mem_%d", i), Content: "memory content"}
@@ -112,8 +113,7 @@ func TestList_Multiple(t *testing.T) {
 }
 
 func TestSearch_ByContent(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	memories := []*Memory{
 		{Content: "Architecture decision: use Go for the backend"},
@@ -136,8 +136,7 @@ func TestSearch_ByContent(t *testing.T) {
 }
 
 func TestSearch_ByTag(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	m := &Memory{Content: "some content", Tags: []string{"golang", "backend"}}
 	if err := Save(m); err != nil {
@@ -154,8 +153,7 @@ func TestSearch_ByTag(t *testing.T) {
 }
 
 func TestSearch_NoMatch(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	m := &Memory{Content: "architecture decision"}
 	if err := Save(m); err != nil {
@@ -172,8 +170,7 @@ func TestSearch_NoMatch(t *testing.T) {
 }
 
 func TestSearch_CaseInsensitive(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	m := &Memory{Content: "IMPORTANT architecture DECISION"}
 	if err := Save(m); err != nil {
@@ -276,8 +273,8 @@ func TestConsolidate_AllUnique(t *testing.T) {
 func TestMemoryDir(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	stateDir := filepath.Join(dir, "state")
-	t.Setenv("HAWK_STATE_DIR", stateDir)
+	storage.SetTestDirs(t, dir)
+	stateDir := storage.StateDir()
 
 	d := memoryDir()
 	if !strings.HasPrefix(d, stateDir) {
@@ -289,10 +286,19 @@ func TestMemoryDir(t *testing.T) {
 }
 
 func TestSaveAndLoad_WithNoHome(t *testing.T) {
+	dir := t.TempDir()
 	t.Setenv("HOME", "/nonexistent-path-12345")
+	storage.SetTestDirs(t, dir)
+
 	m := &Memory{Content: "test"}
-	err := Save(m)
-	if err == nil {
-		_ = os.Remove("/nonexistent-path-12345/.hawk/memories/" + m.ID + ".json")
+	if err := Save(m); err != nil {
+		t.Fatal(err)
+	}
+	loaded, err := Load(m.ID)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.Content != m.Content {
+		t.Fatalf("content mismatch: %q vs %q", loaded.Content, m.Content)
 	}
 }
diff --git a/internal/observability/analytics_test.go b/internal/observability/analytics_test.go
index 6e5b91d6..c7d0ac67 100644
--- a/internal/observability/analytics_test.go
+++ b/internal/observability/analytics_test.go
@@ -6,13 +6,22 @@ import (
 	"strings"
 	"testing"
 	"time"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
+func setTestStorage(t *testing.T) {
+	t.Helper()
+	dir := t.TempDir()
+	t.Setenv("HOME", dir)
+	storage.SetTestDirs(t, dir)
+}
+
 func TestLogEvent(t *testing.T) {
 	dir := t.TempDir()
 	t.Setenv("HOME", dir)
-	stateDir := filepath.Join(dir, "state")
-	t.Setenv("HAWK_STATE_DIR", stateDir)
+	storage.SetTestDirs(t, dir)
+	stateDir := storage.StateDir()
 
 	LogEvent("test_event", "session-123", map[string]interface{}{"key": "value"})
 
@@ -30,8 +39,7 @@ func TestLogEvent(t *testing.T) {
 }
 
 func TestSaveAndGetTraces(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	trace := &SessionTrace{
 		SessionID:    "test-session",
@@ -63,8 +71,7 @@ func TestSaveAndGetTraces(t *testing.T) {
 }
 
 func TestSummary(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	setTestStorage(t)
 
 	// Test empty summary
 	summary := Summary()
diff --git a/internal/session/named_checkpoint_test.go b/internal/session/named_checkpoint_test.go
index 246dc326..75ca10e3 100644
--- a/internal/session/named_checkpoint_test.go
+++ b/internal/session/named_checkpoint_test.go
@@ -7,7 +7,7 @@ import (
 // TestNamedCheckpointRoundTrip verifies a labeled session snapshot saves and
 // restores with full message history, model, and provider intact.
 func TestNamedCheckpointRoundTrip(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	setTestSessionsDir(t, t.TempDir())
 
 	orig := &Session{
 		ID:       "sess-1",
@@ -55,7 +55,7 @@ func TestNamedCheckpointRoundTrip(t *testing.T) {
 // TestNamedCheckpointSnapshotIsImmutable verifies the snapshot is a deep copy:
 // mutating the live session after saving does not change the saved checkpoint.
 func TestNamedCheckpointSnapshotIsImmutable(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	setTestSessionsDir(t, t.TempDir())
 
 	s := &Session{ID: "s", Messages: []Message{{Role: "user", Content: "v1"}}}
 	if _, err := SaveNamedCheckpoint("snap", s); err != nil {
@@ -77,7 +77,7 @@ func TestNamedCheckpointSnapshotIsImmutable(t *testing.T) {
 // TestNamedCheckpointOverwriteAndList verifies re-saving a label overwrites it
 // and that List/Delete behave.
 func TestNamedCheckpointOverwriteAndList(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	setTestSessionsDir(t, t.TempDir())
 
 	if _, err := SaveNamedCheckpoint("a", &Session{ID: "a1"}); err != nil {
 		t.Fatal(err)
@@ -115,7 +115,7 @@ func TestNamedCheckpointOverwriteAndList(t *testing.T) {
 
 // TestNamedCheckpointErrors covers nil/empty inputs and missing checkpoints.
 func TestNamedCheckpointErrors(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	setTestSessionsDir(t, t.TempDir())
 
 	if _, err := SaveNamedCheckpoint("", &Session{}); err == nil {
 		t.Error("expected error for empty name")
diff --git a/internal/session/storage_test_helpers_test.go b/internal/session/storage_test_helpers_test.go
index b8b1245e..d53f89fd 100644
--- a/internal/session/storage_test_helpers_test.go
+++ b/internal/session/storage_test_helpers_test.go
@@ -1,13 +1,13 @@
 package session
 
 import (
-	"path/filepath"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
 )
 
 func setTestSessionsDir(t *testing.T, root string) string {
 	t.Helper()
-	stateDir := filepath.Join(root, "state")
-	t.Setenv("HAWK_STATE_DIR", stateDir)
-	return filepath.Join(stateDir, "sessions")
+	storage.SetTestDirs(t, root)
+	return storage.SessionsDir()
 }
diff --git a/internal/storage/testdirs.go b/internal/storage/testdirs.go
new file mode 100644
index 00000000..36d9fac9
--- /dev/null
+++ b/internal/storage/testdirs.go
@@ -0,0 +1,14 @@
+package storage
+
+import (
+	"path/filepath"
+	"testing"
+)
+
+// SetTestDirs configures isolated Hawk config/state/cache directories for tests.
+func SetTestDirs(t *testing.T, root string) {
+	t.Helper()
+	t.Setenv(envConfigDir, filepath.Join(root, "config"))
+	t.Setenv(envStateDir, filepath.Join(root, "state"))
+	t.Setenv(envCacheDir, filepath.Join(root, "cache"))
+}

From a77dc9286a2f6fcafba955e5bfd6b3ed445bfc02 Mon Sep 17 00:00:00 2001
From: Lakshman Patel <Lakshmanp230@gmail.com>
Date: Sat, 20 Jun 2026 11:09:21 +0530
Subject: [PATCH 3/3] fix(test): isolate Hawk storage dirs across CI race tests

Add testutil.IsolateStorage and route history, config, engine, and
analytics tests through HAWK_* overrides so shuffled CI runs do not read
shared runner state.
---
 cmd/history_test.go                         | 19 ++++++-------
 internal/config/config_test.go              |  5 ++--
 internal/config/setup_status_test.go        |  7 ++---
 internal/engine/adaptive_prompt_test.go     | 31 +++++----------------
 internal/engine/cost/cost_tracker_test.go   | 18 ++++--------
 internal/engine/prompt/prompt_tuner_test.go | 15 ++++------
 internal/engine/scaffold/fewshot_test.go    | 15 ++++------
 internal/testutil/storage.go                | 22 +++++++++++++++
 8 files changed, 57 insertions(+), 75 deletions(-)
 create mode 100644 internal/testutil/storage.go

diff --git a/cmd/history_test.go b/cmd/history_test.go
index dca54ac4..cda9aab7 100644
--- a/cmd/history_test.go
+++ b/cmd/history_test.go
@@ -4,10 +4,12 @@ import (
 	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestLoadInputHistory_Empty(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	testutil.IsolateStorage(t)
 	history := loadInputHistory()
 	if len(history) != 0 {
 		t.Fatalf("expected empty history, got %d entries", len(history))
@@ -15,8 +17,7 @@ func TestLoadInputHistory_Empty(t *testing.T) {
 }
 
 func TestSaveAndLoadInputHistory(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
+	testutil.IsolateStorage(t)
 
 	entries := []string{"hello", "world", "test"}
 	saveInputHistory(entries)
@@ -33,8 +34,7 @@ func TestSaveAndLoadInputHistory(t *testing.T) {
 }
 
 func TestSaveInputHistory_Deduplication(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
+	testutil.IsolateStorage(t)
 
 	entries := []string{"hello", "world", "hello", "test", "world"}
 	saveInputHistory(entries)
@@ -51,8 +51,7 @@ func TestSaveInputHistory_Deduplication(t *testing.T) {
 }
 
 func TestSaveInputHistory_MaxEntries(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
+	testutil.IsolateStorage(t)
 
 	var entries []string
 	for i := 0; i < 1500; i++ {
@@ -67,8 +66,7 @@ func TestSaveInputHistory_MaxEntries(t *testing.T) {
 }
 
 func TestAppendToHistory(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
+	testutil.IsolateStorage(t)
 
 	appendToHistory("first command")
 	appendToHistory("second command")
@@ -83,8 +81,7 @@ func TestAppendToHistory(t *testing.T) {
 }
 
 func TestAppendToHistory_EmptySkipped(t *testing.T) {
-	home := t.TempDir()
-	t.Setenv("HOME", home)
+	testutil.IsolateStorage(t)
 
 	appendToHistory("")
 	appendToHistory("  ")
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 98ba9722..7fc44675 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	"github.com/GrayCodeAI/eyrie/credentials"
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestLoadAgentsMD(t *testing.T) {
@@ -63,7 +64,7 @@ func TestBuildContextWithDirs(t *testing.T) {
 }
 
 func TestLoadSettingsWithJSONOverride(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	testutil.IsolateStorage(t)
 	settings, err := LoadSettingsWithOverride(`{"model":"test-model","allowedTools":["Read"],"disallowedTools":["Write"]}`)
 	if err != nil {
 		t.Fatal(err)
@@ -80,7 +81,7 @@ func TestLoadSettingsWithJSONOverride(t *testing.T) {
 }
 
 func TestLoadSettingsAcceptsArchiveCamelCase(t *testing.T) {
-	t.Setenv("HOME", t.TempDir())
+	testutil.IsolateStorage(t)
 	settings, err := LoadSettingsWithOverride(`{
 		"autoAllow":["Read"],
 		"maxBudgetUSD":1.25,
diff --git a/internal/config/setup_status_test.go b/internal/config/setup_status_test.go
index 0a346c1e..07519af5 100644
--- a/internal/config/setup_status_test.go
+++ b/internal/config/setup_status_test.go
@@ -2,13 +2,12 @@ package config
 
 import (
 	"context"
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 
 	"github.com/GrayCodeAI/eyrie/catalog"
 	"github.com/GrayCodeAI/eyrie/credentials"
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestHasConfiguredDeployment_FromStore(t *testing.T) {
@@ -33,9 +32,7 @@ func (emptyCredentialStore) Delete(context.Context, string) error        { retur
 
 func isolateCredentialEnv(t *testing.T) {
 	t.Helper()
-	home := t.TempDir()
-	_ = os.MkdirAll(filepath.Join(home, ".hawk"), 0o700)
-	t.Setenv("HOME", home)
+	testutil.IsolateStorage(t)
 }
 
 func TestHasConfiguredDeployment_RejectsPlaceholder(t *testing.T) {
diff --git a/internal/engine/adaptive_prompt_test.go b/internal/engine/adaptive_prompt_test.go
index ac3fbe5f..bd0e8da3 100644
--- a/internal/engine/adaptive_prompt_test.go
+++ b/internal/engine/adaptive_prompt_test.go
@@ -1,15 +1,14 @@
 package engine
 
 import (
-	"os"
-	"path/filepath"
 	"strings"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestAdaptivePrompt_New(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
+	testutil.IsolateStorage(t)
 
 	ap := NewAdaptivePrompt()
 	if ap == nil {
@@ -21,11 +20,7 @@ func TestAdaptivePrompt_New(t *testing.T) {
 }
 
 func TestAdaptivePrompt_LearnFromFeedback(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	if err := os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755); err != nil {
-		t.Fatal(err)
-	}
+	testutil.IsolateStorage(t)
 
 	ap := NewAdaptivePrompt()
 
@@ -60,11 +55,7 @@ func TestAdaptivePrompt_LearnFromFeedback(t *testing.T) {
 }
 
 func TestAdaptivePrompt_FormatForPrompt(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	if err := os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755); err != nil {
-		t.Fatal(err)
-	}
+	testutil.IsolateStorage(t)
 
 	ap := NewAdaptivePrompt()
 	ap.LearnFromFeedback("don't add trailing whitespace to files")
@@ -80,11 +71,7 @@ func TestAdaptivePrompt_FormatForPrompt(t *testing.T) {
 }
 
 func TestAdaptivePrompt_Count(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	if err := os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755); err != nil {
-		t.Fatal(err)
-	}
+	testutil.IsolateStorage(t)
 
 	ap := NewAdaptivePrompt()
 	if ap.Count() != 0 {
@@ -98,11 +85,7 @@ func TestAdaptivePrompt_Count(t *testing.T) {
 }
 
 func TestAdaptivePrompt_Persistence(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	if err := os.MkdirAll(filepath.Join(dir, ".hawk"), 0o755); err != nil {
-		t.Fatal(err)
-	}
+	testutil.IsolateStorage(t)
 
 	ap1 := NewAdaptivePrompt()
 	ap1.LearnFromFeedback("don't add unnecessary dependencies")
diff --git a/internal/engine/cost/cost_tracker_test.go b/internal/engine/cost/cost_tracker_test.go
index 1753509c..aca7ffde 100644
--- a/internal/engine/cost/cost_tracker_test.go
+++ b/internal/engine/cost/cost_tracker_test.go
@@ -1,17 +1,15 @@
 package cost
 
 import (
-	"os"
 	"testing"
 	"time"
 
 	analytics "github.com/GrayCodeAI/hawk/internal/observability"
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestCostTracker_NewAndRecord(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	ct := NewCostTracker("test-session")
 	if ct == nil {
@@ -31,9 +29,7 @@ func TestCostTracker_NewAndRecord(t *testing.T) {
 }
 
 func TestCostTracker_SessionTotal(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	ct := NewCostTracker("total-test")
 	_ = ct.Record(analytics.CostEntry{CostUSD: 0.01, Timestamp: time.Now()})
@@ -46,9 +42,7 @@ func TestCostTracker_SessionTotal(t *testing.T) {
 }
 
 func TestCostTracker_Entries(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	ct := NewCostTracker("entries-test")
 	_ = ct.Record(analytics.CostEntry{Model: "m1", CostUSD: 0.01, Timestamp: time.Now()})
@@ -61,9 +55,7 @@ func TestCostTracker_Entries(t *testing.T) {
 }
 
 func TestLoadCostHistory(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	ct := NewCostTracker("history-test")
 	_ = ct.Record(analytics.CostEntry{Model: "test", CostUSD: 0.05, Timestamp: time.Now()})
diff --git a/internal/engine/prompt/prompt_tuner_test.go b/internal/engine/prompt/prompt_tuner_test.go
index 94009b41..a6ee498b 100644
--- a/internal/engine/prompt/prompt_tuner_test.go
+++ b/internal/engine/prompt/prompt_tuner_test.go
@@ -1,14 +1,13 @@
 package prompt
 
 import (
-	"os"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestPromptTuner_RecordAndBest(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	pt := NewPromptTuner()
 	pt.RecordOutcome("tools", "Use tools freely", true)
@@ -20,9 +19,7 @@ func TestPromptTuner_RecordAndBest(t *testing.T) {
 }
 
 func TestPromptTuner_Report(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	pt := NewPromptTuner()
 	pt.RecordOutcome("style", "concise", true)
@@ -35,9 +32,7 @@ func TestPromptTuner_Report(t *testing.T) {
 }
 
 func TestPromptTuner_BestVariant_Empty(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	pt := NewPromptTuner()
 	best, _ := pt.BestVariant("nonexistent")
diff --git a/internal/engine/scaffold/fewshot_test.go b/internal/engine/scaffold/fewshot_test.go
index 03b1497e..238600e3 100644
--- a/internal/engine/scaffold/fewshot_test.go
+++ b/internal/engine/scaffold/fewshot_test.go
@@ -1,14 +1,13 @@
 package scaffold
 
 import (
-	"os"
 	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/testutil"
 )
 
 func TestFewShotStore_RecordAndRetrieve(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	fs := NewFewShotStore()
 	fs.Record("fix the login bug", "I fixed it by adding nil check", "debug")
@@ -20,9 +19,7 @@ func TestFewShotStore_RecordAndRetrieve(t *testing.T) {
 }
 
 func TestFewShotStore_FormatForPrompt(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	fs := NewFewShotStore()
 	fs.Record("write tests", "Added table-driven tests", "test")
@@ -32,9 +29,7 @@ func TestFewShotStore_FormatForPrompt(t *testing.T) {
 }
 
 func TestFewShotStore_Empty(t *testing.T) {
-	dir := t.TempDir()
-	t.Setenv("HOME", dir)
-	_ = os.MkdirAll(dir+"/.hawk", 0o755)
+	testutil.IsolateStorage(t)
 
 	fs := NewFewShotStore()
 	results := fs.Retrieve("anything", 5)
diff --git a/internal/testutil/storage.go b/internal/testutil/storage.go
new file mode 100644
index 00000000..fb0f5c01
--- /dev/null
+++ b/internal/testutil/storage.go
@@ -0,0 +1,22 @@
+package testutil
+
+import (
+	"testing"
+
+	"github.com/GrayCodeAI/hawk/internal/storage"
+)
+
+// IsolateStorage configures isolated HOME and Hawk config/state/cache dirs for tests.
+func IsolateStorage(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	IsolateStorageIn(t, root)
+	return root
+}
+
+// IsolateStorageIn configures isolated HOME and Hawk config/state/cache dirs rooted at root.
+func IsolateStorageIn(t *testing.T, root string) {
+	t.Helper()
+	t.Setenv("HOME", root)
+	storage.SetTestDirs(t, root)
+}