diff --git a/README.md b/README.md
index c5ef1e0..7304917 100644
--- a/README.md
+++ b/README.md
@@ -148,7 +148,7 @@ See [docs/AGENT_BUILDER.md](docs/AGENT_BUILDER.md) for comprehensive documentati
 |------|-----------------|-------------|
 | File System | `fs.NewFsTool(root)` | File operations within root directory |
 | Git | `git.NewGitTool(repoRoot)` | Git operations (add, commit, push, etc.) |
-| Web | `web.NewWebTool(workingDir)` | Web automation with headless browser |
+| Web | `web.NewWebTool(workingDir)` | Web automation with browser sessions; headless by default |
 | Postgres | `postgres.NewPostgresTool(url, mode, tables, schemas)` | Database operations with whitelisting |
 | API | `api.NewApiTool(name, endpoints, authHook)` | HTTP API calls with auth support |
 | Vector | `vector.NewVectorTool(db, embeddings)` | Semantic search and indexing |
diff --git a/VERSION b/VERSION
index a918a2a..ee6cdce 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.6.0
+0.6.1
diff --git a/cmd/localforge/src/auth/config.go b/cmd/localforge/src/auth/config.go
new file mode 100644
index 0000000..889d09e
--- /dev/null
+++ b/cmd/localforge/src/auth/config.go
@@ -0,0 +1,71 @@
+package auth
+
+import (
+	"net/http"
+	"os"
+	"strings"
+	"time"
+)
+
+const (
+	DefaultCookieName = "localforge_session"
+	DefaultSessionTTL = 24 * time.Hour
+)
+
+type Config struct {
+	Enabled      bool
+	Username     string
+	PasswordHash string
+	CookieName   string
+	SessionTTL   time.Duration
+	SecureCookie bool
+}
+
+func LoadConfigFromEnv() Config {
+	cfg := Config{
+		Username:     strings.TrimSpace(os.Getenv("AUTH_USERNAME")),
+		PasswordHash: strings.TrimSpace(os.Getenv("AUTH_PASSWORD_HASH")),
+		CookieName:   DefaultCookieName,
+		SessionTTL:   DefaultSessionTTL,
+		SecureCookie: parseBoolEnv("AUTH_COOKIE_SECURE"),
+	}
+
+	if cookieName := strings.TrimSpace(os.Getenv("AUTH_COOKIE_NAME")); cookieName != "" {
+		cfg.CookieName = cookieName
+	}
+
+	if ttlRaw := strings.TrimSpace(os.Getenv("AUTH_SESSION_TTL")); ttlRaw != "" {
+		if ttl, err := time.ParseDuration(ttlRaw); err == nil && ttl > 0 {
+			cfg.SessionTTL = ttl
+		}
+	}
+
+	cfg.Enabled = cfg.Username != "" && cfg.PasswordHash != ""
+	return cfg
+}
+
+func parseBoolEnv(key string) bool {
+	switch strings.ToLower(strings.TrimSpace(os.Getenv(key))) {
+	case "1", "true", "yes", "on":
+		return true
+	default:
+		return false
+	}
+}
+
+func (c Config) CookieMaxAgeSeconds() int {
+	return int(c.SessionTTL.Seconds())
+}
+
+func (c Config) ShouldUseSecureCookie(r *http.Request) bool {
+	if c.SecureCookie {
+		return true
+	}
+	if r == nil {
+		return false
+	}
+	if r.TLS != nil {
+		return true
+	}
+	return strings.EqualFold(r.Header.Get("X-Forwarded-Proto"), "https")
+}
diff --git a/cmd/localforge/src/auth/middleware.go b/cmd/localforge/src/auth/middleware.go
new file mode 100644
index 0000000..f4de979
--- /dev/null
+++ b/cmd/localforge/src/auth/middleware.go
@@ -0,0 +1,77 @@
+package auth
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+const sessionContextKey = "localforge.auth.session"
+
+type UnauthorizedMode int
+
+const (
+	UnauthorizedJSON UnauthorizedMode = iota
+	UnauthorizedRedirect
+)
+
+func Middleware(cfg Config, store *SessionStore, mode UnauthorizedMode) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if !cfg.Enabled {
+			c.Next()
+			return
+		}
+
+		token, err := c.Cookie(cfg.CookieName)
+		if err == nil && token != "" {
+			session, ok := store.Get(token)
+			if ok {
+				c.Set(sessionContextKey, session)
+				c.Next()
+				return
+			}
+
+			clearSessionCookie(c, cfg)
+		}
+
+		switch mode {
+		case UnauthorizedRedirect:
+			next := SafeNextPath(c.Request.URL.RequestURI())
+			c.Redirect(http.StatusFound, "/login?next="+url.QueryEscape(next))
+			c.Abort()
+		default:
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "unauthorized"})
+		}
+	}
+}
+
+func CurrentSession(c *gin.Context) (Session, bool) {
+	value, ok := c.Get(sessionContextKey)
+	if !ok {
+		return Session{}, false
+	}
+
+	session, ok := value.(Session)
+	return session, ok
+}
+
+func clearSessionCookie(c *gin.Context, cfg Config) {
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     cfg.CookieName,
+		Value:    "",
+		Path:     "/",
+		MaxAge:   -1,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Secure:   cfg.ShouldUseSecureCookie(c.Request),
+	})
+}
+
+func SafeNextPath(next string) string {
+	if next == "" || !strings.HasPrefix(next, "/") || strings.HasPrefix(next, "//") {
+		return "/"
+	}
+	return next
+}
diff --git a/cmd/localforge/src/auth/password.go b/cmd/localforge/src/auth/password.go
new file mode 100644
index 0000000..97622ae
--- /dev/null
+++ b/cmd/localforge/src/auth/password.go
@@ -0,0 +1,10 @@
+package auth
+
+import "golang.org/x/crypto/bcrypt"
+
+func VerifyPassword(password, hash string) bool {
+	if password == "" || hash == "" {
+		return false
+	}
+	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(password)) == nil
+}
diff --git a/cmd/localforge/src/auth/session_store.go b/cmd/localforge/src/auth/session_store.go
new file mode 100644
index 0000000..013416e
--- /dev/null
+++ b/cmd/localforge/src/auth/session_store.go
@@ -0,0 +1,106 @@
+package auth
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"sync"
+	"time"
+)
+
+type Session struct {
+	Username  string
+	TokenHash string
+	ExpiresAt time.Time
+}
+
+type SessionStore struct {
+	mu       sync.RWMutex
+	sessions map[string]Session
+}
+
+func NewSessionStore() *SessionStore {
+	return &SessionStore{
+		sessions: make(map[string]Session),
+	}
+}
+
+func (s *SessionStore) Create(username string, ttl time.Duration) (string, Session, error) {
+	token, err := randomToken()
+	if err != nil {
+		return "", Session{}, err
+	}
+
+	session := Session{
+		Username:  username,
+		TokenHash: hashToken(token),
+		ExpiresAt: time.Now().UTC().Add(ttl),
+	}
+
+	s.mu.Lock()
+	s.sessions[session.TokenHash] = session
+	s.mu.Unlock()
+
+	return token, session, nil
+}
+
+func (s *SessionStore) Get(token string) (Session, bool) {
+	tokenHash := hashToken(token)
+
+	s.mu.RLock()
+	session, ok := s.sessions[tokenHash]
+	s.mu.RUnlock()
+	if !ok {
+		return Session{}, false
+	}
+	if time.Now().UTC().After(session.ExpiresAt) {
+		s.Delete(token)
+		return Session{}, false
+	}
+	return session, true
+}
+
+func (s *SessionStore) Delete(token string) {
+	s.mu.Lock()
+	delete(s.sessions, hashToken(token))
+	s.mu.Unlock()
+}
+
+func (s *SessionStore) CleanupExpired() {
+	now := time.Now().UTC()
+
+	s.mu.Lock()
+	for key, session := range s.sessions {
+		if now.After(session.ExpiresAt) {
+			delete(s.sessions, key)
+		}
+	}
+	s.mu.Unlock()
+}
+
+func (s *SessionStore) StartCleanup(interval time.Duration) {
+	if interval <= 0 {
+		interval = time.Hour
+	}
+
+	go func() {
+		ticker := time.NewTicker(interval)
+		defer ticker.Stop()
+		for range ticker.C {
+			s.CleanupExpired()
+		}
+	}()
+}
+
+func hashToken(token string) string {
+	sum := sha256.Sum256([]byte(token))
+	return hex.EncodeToString(sum[:])
+}
+
+func randomToken() (string, error) {
+	buf := make([]byte, 32)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(buf), nil
+}
diff --git a/cmd/localforge/src/handlers_auth.go b/cmd/localforge/src/handlers_auth.go
new file mode 100644
index 0000000..0c31b6e
--- /dev/null
+++ b/cmd/localforge/src/handlers_auth.go
@@ -0,0 +1,115 @@
+package main
+
+import (
+	"crypto/subtle"
+	"io/fs"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	localauth "github.com/thinktwiceco/agent-forge/cmd/localforge/src/auth"
+)
+
+func (s *Server) handleLoginPage(c *gin.Context) {
+	if !s.authConfig.Enabled {
+		c.Redirect(http.StatusFound, "/")
+		return
+	}
+
+	if token, err := c.Cookie(s.authConfig.CookieName); err == nil && token != "" {
+		if _, ok := s.sessionStore.Get(token); ok {
+			c.Redirect(http.StatusFound, requestedNextPath(c))
+			return
+		}
+	}
+
+	data, err := fs.ReadFile(s.staticFS, "login.html")
+	if err != nil {
+		c.String(http.StatusNotFound, "login.html not found")
+		return
+	}
+	c.Data(http.StatusOK, "text/html; charset=utf-8", data)
+}
+
+func (s *Server) handleAuthLogin(c *gin.Context) {
+	if !s.authConfig.Enabled {
+		c.JSON(http.StatusNotFound, gin.H{"error": "authentication is disabled"})
+		return
+	}
+
+	var req LoginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"})
+		return
+	}
+
+	if subtle.ConstantTimeCompare([]byte(req.Username), []byte(s.authConfig.Username)) != 1 ||
+		!localauth.VerifyPassword(req.Password, s.authConfig.PasswordHash) {
+		c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid username or password"})
+		return
+	}
+
+	token, session, err := s.sessionStore.Create(s.authConfig.Username, s.authConfig.SessionTTL)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create session"})
+		return
+	}
+
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     s.authConfig.CookieName,
+		Value:    token,
+		Path:     "/",
+		MaxAge:   s.authConfig.CookieMaxAgeSeconds(),
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Secure:   s.authConfig.ShouldUseSecureCookie(c.Request),
+	})
+
+	c.JSON(http.StatusOK, AuthStatusResponse{
+		Enabled:       true,
+		Authenticated: true,
+		Username:      session.Username,
+		Next:          requestedNextPath(c),
+	})
+}
+
+func (s *Server) handleAuthLogout(c *gin.Context) {
+	if token, err := c.Cookie(s.authConfig.CookieName); err == nil && token != "" {
+		s.sessionStore.Delete(token)
+	}
+
+	http.SetCookie(c.Writer, &http.Cookie{
+		Name:     s.authConfig.CookieName,
+		Value:    "",
+		Path:     "/",
+		MaxAge:   -1,
+		HttpOnly: true,
+		SameSite: http.SameSiteLaxMode,
+		Secure:   s.authConfig.ShouldUseSecureCookie(c.Request),
+	})
+
+	c.Status(http.StatusNoContent)
+}
+
+func (s *Server) handleAuthMe(c *gin.Context) {
+	resp := AuthStatusResponse{
+		Enabled: s.authConfig.Enabled,
+		Next:    requestedNextPath(c),
+	}
+	if !s.authConfig.Enabled {
+		c.JSON(http.StatusOK, resp)
+		return
+	}
+
+	if token, err := c.Cookie(s.authConfig.CookieName); err == nil && token != "" {
+		if session, ok := s.sessionStore.Get(token); ok {
+			resp.Authenticated = true
+			resp.Username = session.Username
+		}
+	}
+
+	c.JSON(http.StatusOK, resp)
+}
+
+func requestedNextPath(c *gin.Context) string {
+	return localauth.SafeNextPath(c.Query("next"))
+}
diff --git a/cmd/localforge/src/server.go b/cmd/localforge/src/server.go
index 08c5783..9d88956 100644
--- a/cmd/localforge/src/server.go
+++ b/cmd/localforge/src/server.go
@@ -9,9 +9,12 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
+	"time"
 
 	"github.com/gin-gonic/gin"
 	_ "github.com/mattn/go-sqlite3"
+	localauth "github.com/thinktwiceco/agent-forge/cmd/localforge/src/auth"
 	"github.com/thinktwiceco/agent-forge/cmd/localforge/src/providers"
 )
 
@@ -30,11 +33,15 @@ type Server struct {
 	knowledgeDB      *sql.DB // opened once at startup; nil if DB not yet available
 	devMode          bool
 	appDir           string
+	staticFS         fs.FS
+	authConfig       localauth.Config
+	sessionStore     *localauth.SessionStore
 }
 
 func NewServer(agentMgr *AgentManager, configMgr *ConfigManager, todoMgr *TodoManager, devMode bool, appDir string) *Server {
+	authConfig := localauth.LoadConfigFromEnv()
 	engine := gin.New()
-	engine.Use(gin.Logger(), gin.Recovery(), corsMiddleware())
+	engine.Use(gin.Logger(), gin.Recovery(), corsMiddleware(authConfig.Enabled))
 
 	// Initialize provider registry
 	providerRegistry := NewProviderRegistry()
@@ -59,6 +66,17 @@ func NewServer(agentMgr *AgentManager, configMgr *ConfigManager, todoMgr *TodoMa
 		providerRegistry: providerRegistry,
 		devMode:          devMode,
 		appDir:           appDir,
+		authConfig:       authConfig,
+		sessionStore:     localauth.NewSessionStore(),
+	}
+
+	staticFS, err := server.staticFileSystem()
+	if err != nil {
+		panic(err)
+	}
+	server.staticFS = staticFS
+	if authConfig.Enabled {
+		server.sessionStore.StartCleanup(time.Hour)
 	}
 
 	// Open the knowledge DB once so all handlers share a connection pool.
@@ -101,14 +119,9 @@ func (s *Server) staticFileSystem() (fs.FS, error) {
 }
 
 func (s *Server) setupRoutes() {
-	staticFS, err := s.staticFileSystem()
-	if err != nil {
-		panic(err)
-	}
-
 	// Serve static files. In dev mode wrap the handler to disable browser caching
 	// so file edits are visible immediately without a hard refresh.
-	staticHandler := http.StripPrefix("/static", http.FileServer(http.FS(staticFS)))
+	staticHandler := http.StripPrefix("/static", http.FileServer(http.FS(s.staticFS)))
 	if s.devMode {
 		original := staticHandler
 		staticHandler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -122,35 +135,23 @@ func (s *Server) setupRoutes() {
 	s.engine.HEAD("/static/*filepath", func(c *gin.Context) {
 		staticHandler.ServeHTTP(c.Writer, c.Request)
 	})
+	s.engine.GET("/login", s.handleLoginPage)
 
-	s.engine.GET("/", func(c *gin.Context) {
-		data, err := fs.ReadFile(staticFS, "index.html")
-		if err != nil {
-			c.String(http.StatusNotFound, "index.html not found")
-			return
-		}
-		c.Data(http.StatusOK, "text/html; charset=utf-8", data)
-	})
-
-	s.engine.GET("/knowledge", func(c *gin.Context) {
-		data, err := fs.ReadFile(staticFS, "knowledge.html")
-		if err != nil {
-			c.String(http.StatusNotFound, "knowledge.html not found")
-			return
-		}
-		c.Data(http.StatusOK, "text/html; charset=utf-8", data)
-	})
+	pageRoutes := s.engine.Group("")
+	pageRoutes.Use(localauth.Middleware(s.authConfig, s.sessionStore, localauth.UnauthorizedRedirect))
+	pageRoutes.GET("/", s.serveStaticPage("index.html"))
+	pageRoutes.GET("/knowledge", s.serveStaticPage("knowledge.html"))
+	pageRoutes.GET("/settings", s.serveStaticPage("settings.html"))
 
-	s.engine.GET("/settings", func(c *gin.Context) {
-		data, err := fs.ReadFile(staticFS, "settings.html")
-		if err != nil {
-			c.String(http.StatusNotFound, "settings.html not found")
-			return
-		}
-		c.Data(http.StatusOK, "text/html; charset=utf-8", data)
-	})
+	publicAPI := s.engine.Group("/api")
+	publicAPI.GET("/auth/me", s.handleAuthMe)
+	publicAPI.POST("/auth/login", s.handleAuthLogin)
+	publicAPI.POST("/auth/logout", s.handleAuthLogout)
+	publicAPI.POST("/webhooks/:provider", s.handleWebhook)
+	publicAPI.POST("/webhooks/:provider/sync", s.handleWebhookSync)
 
 	api := s.engine.Group("/api")
+	api.Use(localauth.Middleware(s.authConfig, s.sessionStore, localauth.UnauthorizedJSON))
 	api.POST("/chat", s.handleChat)
 	api.POST("/chat/stop", s.handleStopChat)
 	api.POST("/upload", s.handleUpload)
@@ -177,10 +178,6 @@ func (s *Server) setupRoutes() {
 	api.GET("/knowledge/graph", s.handleGetKnowledgeGraph)
 	api.GET("/knowledge/stats", s.handleGetKnowledgeStats)
 	api.GET("/knowledge/node/:id", s.handleGetKnowledgeNode)
-
-	// Webhook endpoints
-	api.POST("/webhooks/:provider", s.handleWebhook)
-	api.POST("/webhooks/:provider/sync", s.handleWebhookSync)
 }
 
 func (s *Server) Run(port string) error {
@@ -204,11 +201,29 @@ func (s *Server) Shutdown(ctx context.Context) error {
 	return s.httpSrv.Shutdown(ctx)
 }
 
-func corsMiddleware() gin.HandlerFunc {
+func (s *Server) serveStaticPage(name string) gin.HandlerFunc {
 	return func(c *gin.Context) {
-		c.Header("Access-Control-Allow-Origin", "*")
-		c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
-		c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+		data, err := fs.ReadFile(s.staticFS, name)
+		if err != nil {
+			c.String(http.StatusNotFound, "%s not found", name)
+			return
+		}
+		c.Data(http.StatusOK, "text/html; charset=utf-8", data)
+	}
+}
+
+func corsMiddleware(authEnabled bool) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if !authEnabled {
+			c.Header("Access-Control-Allow-Origin", "*")
+			c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
+			c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+		} else if origin := c.Request.Header.Get("Origin"); origin != "" && sameOrigin(origin, c.Request.Host) {
+			c.Header("Access-Control-Allow-Origin", origin)
+			c.Header("Vary", "Origin")
+			c.Header("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS")
+			c.Header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+		}
 		if c.Request.Method == http.MethodOptions {
 			c.AbortWithStatus(http.StatusNoContent)
 			return
@@ -216,3 +231,11 @@ func corsMiddleware() gin.HandlerFunc {
 		c.Next()
 	}
 }
+
+func sameOrigin(origin string, host string) bool {
+	trimmed := strings.TrimSpace(origin)
+	if trimmed == "" {
+		return false
+	}
+	return strings.HasSuffix(trimmed, "://"+host)
+}
diff --git a/cmd/localforge/src/static/index.html b/cmd/localforge/src/static/index.html
index 61f0a71..7286652 100644
--- a/cmd/localforge/src/static/index.html
+++ b/cmd/localforge/src/static/index.html
@@ -16,7 +16,10 @@
           <span class="brand-icon">✦</span>
           <span class="brand-name" id="agent-name-label">ThinkTwice</span>
         </div>
-        <button id="new-chat" class="btn">New</button>
+        <div style="display: flex; gap: 8px;">
+          <button id="new-chat" class="btn">New</button>
+          <button class="btn" data-auth-logout hidden>Logout</button>
+        </div>
       </div>
       <div class="sidebar-nav"
         style="display: flex; gap: 8px; padding-bottom: 12px; border-bottom: 1px solid var(--border); margin-bottom: 12px;">
diff --git a/cmd/localforge/src/static/js/app.js b/cmd/localforge/src/static/js/app.js
index 2e26f1c..e1ec09f 100644
--- a/cmd/localforge/src/static/js/app.js
+++ b/cmd/localforge/src/static/js/app.js
@@ -2,6 +2,7 @@ import { ChatManager } from "./chat.js";
 import { ConversationManager } from "./conversations.js";
 import { TodoManager } from "./todos.js";
 import { FileSystemManager } from "./fs.js";
+import { setupAuthUI } from "./auth.js";
 
 function loadConversationId() {
   return localStorage.getItem('currentConversationId') || '';
@@ -41,6 +42,7 @@ async function loadAgentName() {
 }
 
 async function bootstrap() {
+  await setupAuthUI();
   await loadAgentName();
   await conversationManager.refreshList();
   conversationManager.bindNewChat();
diff --git a/cmd/localforge/src/static/js/auth.js b/cmd/localforge/src/static/js/auth.js
new file mode 100644
index 0000000..86b05b9
--- /dev/null
+++ b/cmd/localforge/src/static/js/auth.js
@@ -0,0 +1,100 @@
+function desiredNextPath() {
+  const current = window.location.pathname + window.location.search;
+  if (window.location.pathname !== "/login") {
+    return current;
+  }
+
+  const params = new URLSearchParams(window.location.search);
+  return params.get("next") || "/";
+}
+
+async function getAuthStatus() {
+  try {
+    const next = encodeURIComponent(desiredNextPath());
+    const res = await fetch(`/api/auth/me?next=${next}`);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+async function logout() {
+  await fetch("/api/auth/logout", { method: "POST" });
+  window.location.href = "/login";
+}
+
+export async function setupAuthUI() {
+  const status = await getAuthStatus();
+  const buttons = document.querySelectorAll("[data-auth-logout]");
+
+  if (!status?.enabled) {
+    buttons.forEach((button) => {
+      button.hidden = true;
+    });
+    return status;
+  }
+
+  buttons.forEach((button) => {
+    button.hidden = false;
+    if (button.dataset.authBound === "true") return;
+    button.dataset.authBound = "true";
+    button.addEventListener("click", async () => {
+      button.disabled = true;
+      try {
+        await logout();
+      } finally {
+        button.disabled = false;
+      }
+    });
+  });
+
+  return status;
+}
+
+export async function setupLoginForm() {
+  const form = document.getElementById("login-form");
+  const message = document.getElementById("login-message");
+  if (!form || !message) return;
+
+  const status = await getAuthStatus();
+  if (status?.enabled === false) {
+    window.location.replace("/");
+    return;
+  }
+  if (status?.authenticated) {
+    window.location.replace(status.next || "/");
+    return;
+  }
+
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    message.textContent = "";
+
+    const username = document.getElementById("login-username")?.value || "";
+    const password = document.getElementById("login-password")?.value || "";
+    const submit = form.querySelector('button[type="submit"]');
+    if (submit) submit.disabled = true;
+
+    try {
+      const next = encodeURIComponent(desiredNextPath());
+      const res = await fetch(`/api/auth/login?next=${next}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ username, password }),
+      });
+
+      const payload = await res.json().catch(() => ({}));
+      if (!res.ok) {
+        message.textContent = payload.error || "Login failed";
+        return;
+      }
+
+      window.location.replace(payload.next || "/");
+    } catch {
+      message.textContent = "Network error";
+    } finally {
+      if (submit) submit.disabled = false;
+    }
+  });
+}
diff --git a/cmd/localforge/src/static/js/knowledge.js b/cmd/localforge/src/static/js/knowledge.js
index d1de741..24af56d 100644
--- a/cmd/localforge/src/static/js/knowledge.js
+++ b/cmd/localforge/src/static/js/knowledge.js
@@ -1,3 +1,5 @@
+import { setupAuthUI } from "./auth.js";
+
 // Knowledge Graph Visualization with D3.js
 
 class KnowledgeGraph {
@@ -612,4 +614,7 @@ class KnowledgeGraph {
 }
 
 const graph = new KnowledgeGraph();
-graph.init();
+(async () => {
+  await setupAuthUI();
+  await graph.init();
+})();
diff --git a/cmd/localforge/src/static/js/settings.js b/cmd/localforge/src/static/js/settings.js
index b3dca5b..2be4f70 100644
--- a/cmd/localforge/src/static/js/settings.js
+++ b/cmd/localforge/src/static/js/settings.js
@@ -1,3 +1,5 @@
+import { setupAuthUI } from "./auth.js";
+
 // All known plugins the registry supports.
 const ALL_PLUGINS = ["todo", "procedures", "vault", "knowledge", "scheduler", "logger"];
 
@@ -413,4 +415,7 @@ function _setStatus(el, msg, ok) {
 // ─── Init ─────────────────────────────────────────────────────────────────────
 
 const settings = new SettingsManager();
-settings.load();
+(async () => {
+  await setupAuthUI();
+  await settings.load();
+})();
diff --git a/cmd/localforge/src/static/knowledge.html b/cmd/localforge/src/static/knowledge.html
index 2f4e140..d0babbd 100644
--- a/cmd/localforge/src/static/knowledge.html
+++ b/cmd/localforge/src/static/knowledge.html
@@ -15,7 +15,10 @@
             <span class="brand-icon">✦</span>
             <span class="brand-name">Knowledge Graph</span>
           </div>
-          <a href="/" class="btn btn-back">← Back to Chat</a>
+          <div style="display: flex; gap: 8px;">
+            <a href="/" class="btn btn-back">← Back to Chat</a>
+            <button class="btn" data-auth-logout hidden>Logout</button>
+          </div>
         </div>
 
         <div class="search-section">
diff --git a/cmd/localforge/src/static/login.html b/cmd/localforge/src/static/login.html
new file mode 100644
index 0000000..c46c557
--- /dev/null
+++ b/cmd/localforge/src/static/login.html
@@ -0,0 +1,109 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Login</title>
+  <link rel="stylesheet" href="/static/css/styles.css" />
+  <style>
+    body {
+      overflow: auto;
+    }
+
+    .login-shell {
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+    }
+
+    .login-card {
+      width: 100%;
+      max-width: 380px;
+      background: var(--bg-panel);
+      border: 1px solid var(--border);
+      border-radius: var(--radius-md);
+      padding: 24px;
+      box-shadow: 0 18px 60px rgba(0, 0, 0, 0.35);
+    }
+
+    .login-card h1 {
+      margin: 0 0 8px 0;
+      font-size: 22px;
+    }
+
+    .login-copy {
+      margin: 0 0 20px 0;
+      color: var(--text-muted);
+    }
+
+    .login-field {
+      margin-bottom: 14px;
+    }
+
+    .login-field label {
+      display: block;
+      margin-bottom: 6px;
+      color: var(--text-muted);
+      font-size: 12px;
+      font-weight: 500;
+    }
+
+    .login-field input {
+      width: 100%;
+      background: var(--bg-input);
+      border: 1px solid var(--border);
+      border-radius: var(--radius-sm);
+      color: var(--text-primary);
+      font-size: 14px;
+      padding: 10px 12px;
+    }
+
+    .login-field input:focus {
+      outline: none;
+      border-color: var(--border-active);
+    }
+
+    .login-message {
+      min-height: 20px;
+      margin-top: 12px;
+      color: var(--error);
+      font-size: 13px;
+    }
+  </style>
+</head>
+
+<body>
+  <main class="login-shell">
+    <section class="login-card">
+      <div class="brand" style="margin-bottom: 16px;">
+        <span class="brand-icon">✦</span>
+        <span class="brand-name">ThinkTwice Agent</span>
+      </div>
+      <h1>Sign in</h1>
+      <p class="login-copy">Use the localforge admin credentials configured in the environment.</p>
+
+      <form id="login-form">
+        <div class="login-field">
+          <label for="login-username">Username</label>
+          <input id="login-username" name="username" type="text" autocomplete="username" required />
+        </div>
+        <div class="login-field">
+          <label for="login-password">Password</label>
+          <input id="login-password" name="password" type="password" autocomplete="current-password" required />
+        </div>
+        <button type="submit" class="btn primary" style="width: 100%;">Login</button>
+        <div id="login-message" class="login-message" aria-live="polite"></div>
+      </form>
+    </section>
+  </main>
+
+  <script type="module">
+    import { setupLoginForm } from "/static/js/auth.js";
+    setupLoginForm();
+  </script>
+</body>
+
+</html>
diff --git a/cmd/localforge/src/static/settings.html b/cmd/localforge/src/static/settings.html
index 9a11b8d..671774a 100644
--- a/cmd/localforge/src/static/settings.html
+++ b/cmd/localforge/src/static/settings.html
@@ -25,6 +25,7 @@
     .settings-nav-header {
       display: flex;
       align-items: center;
+      justify-content: space-between;
       gap: 10px;
       padding-bottom: 12px;
       margin-bottom: 16px;
@@ -41,6 +42,13 @@
       color: var(--text-primary);
     }
 
+    .settings-nav-header-left {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      min-width: 0;
+    }
+
     .settings-nav-title {
       font-size: 15px;
       font-weight: 600;
@@ -350,8 +358,11 @@
     <!-- Left nav -->
     <nav class="settings-nav">
       <div class="settings-nav-header">
-        <a href="/">← Back</a>
-        <span class="settings-nav-title">Settings</span>
+          <div class="settings-nav-header-left">
+            <a href="/">← Back</a>
+            <span class="settings-nav-title">Settings</span>
+          </div>
+          <button class="btn" data-auth-logout hidden>Logout</button>
       </div>
       <button class="settings-nav-item active" data-section="agent">Agent</button>
       <button class="settings-nav-item" data-section="subagents">Sub-agents</button>
diff --git a/cmd/localforge/src/types.go b/cmd/localforge/src/types.go
index 81e4089..845ca93 100644
--- a/cmd/localforge/src/types.go
+++ b/cmd/localforge/src/types.go
@@ -92,6 +92,20 @@ type UpdateProvidersRequest struct {
 	Providers map[string]string `json:"providers" binding:"required"`
 }
 
+// ─── Authentication ───────────────────────────────────────────────────────────
+
+type LoginRequest struct {
+	Username string `json:"username" binding:"required"`
+	Password string `json:"password" binding:"required"`
+}
+
+type AuthStatusResponse struct {
+	Enabled       bool   `json:"enabled"`
+	Authenticated bool   `json:"authenticated"`
+	Username      string `json:"username,omitempty"`
+	Next          string `json:"next,omitempty"`
+}
+
 // ─── SSE event names ──────────────────────────────────────────────────────────
 
 type ProviderContext struct {
diff --git a/docs/TOOLS.md b/docs/TOOLS.md
index f9f810a..219ce25 100644
--- a/docs/TOOLS.md
+++ b/docs/TOOLS.md
@@ -10,6 +10,7 @@ Agent Forge includes several built-in tools that extend agent capabilities. This
 - [Postgres Tool](#postgres-tool)
 - [API Tool](#api-tool)
 - [Web Browser Tool](#web-browser-tool)
+- [Update Tool](#update-tool)
 - [Vector Database Tool](#vector-database-tool)
 - [Creating Custom Tools](#creating-custom-tools)
 
@@ -300,7 +301,7 @@ See:
 
 ## Web Browser Tool
 
-The web browser tool provides web automation using a headless browser.
+The web browser tool provides web automation using a browser that runs headlessly by default. Set `WEB_TOOL_HEADLESS=false` to make new sessions visible by default.
 
 ### Basic Usage
 
@@ -338,6 +339,38 @@ tools:
     root: "/path/to/working/dir"
 ```
 
+## Update Tool
+
+The update tool runs the root `update-release.sh` script for an agent installation.
+
+### Basic Usage
+
+```go
+import "github.com/thinktwiceco/agent-forge/src/tools/update"
+
+// Create tool for an agent working directory
+updateTool := update.NewUpdateTool("/path/to/agent/root")
+
+// Add to agent
+agent := agents.NewAgent(&agents.AgentConfig{
+    Tools: []llms.Tool{updateTool},
+})
+```
+
+### Behavior
+
+- Resolves exactly `./update-release.sh` in the configured agent root
+- Refuses to run if the script is missing or not a regular file
+- Executes the script with `bash` from the agent root
+- Returns captured stdout and stderr so the caller can inspect the update result
+
+### YAML Configuration
+
+```yaml
+tools:
+  - name: "update"
+```
+
 ## Vector Database Tool
 
 The vector database tool enables semantic search over indexed documents.
diff --git a/src/agents/prompts/files/system-agents/vector.md b/src/agents/prompts/files/system-agents/vector.md
deleted file mode 100644
index 393688a..0000000
--- a/src/agents/prompts/files/system-agents/vector.md
+++ /dev/null
@@ -1,96 +0,0 @@
-## Incipit
-
-[ROLE] Vector database specialist. Operations: index, search, delete.
-
-[ANALYZE TASK]
-- Documents to index?
-- Semantic searches needed?
-- Documents to delete?
-- Metadata to associate?
-- Filters for search?
-
-## Steps
-
-- Step 1: Identify vector operations needed
-- Step 2: Determine action: index, search, delete
-- Step 3: Extract/prepare parameters
-- Step 4: Execute via vector_db tool
-- Step 5: Format and return results
-
-## Output
-
-- Always specify action: index, search, delete
-- index: text required, metadata/document_id optional
-- search: query required, top_k/filters optional
-- delete: document_id required
-- Return operation results only (IDs, scores, etc.)
-- Report errors only when operations fail
-
-## Examples
-
----
-'user': Index document "Machine learning is a subset of artificial intelligence"
-
-'assistant':
-[Uses vector_db: action="index", text="Machine learning is a subset of artificial intelligence"]
-Document indexed. ID: 550e8400-e29b-41d4-a716-446655440000
-
----
-'user': Search for "AI and neural networks"
-
-'assistant':
-[Uses vector_db: action="search", query="AI and neural networks", top_k=10]
-Results: [{"text":"...","similarity":0.87}]
-
----
-'user': Delete document 550e8400-e29b-41d4-a716-446655440000
-
-'assistant':
-[Uses vector_db: action="delete", document_id="550e8400-e29b-41d4-a716-446655440000"]
-Deleted successfully.
-
----
-'user': Index with metadata {"category":"programming","language":"python"}
-
-'assistant':
-[Uses vector_db: action="index", text="...", metadata={...}]
-Indexed. ID: 660e8400-e29b-41d4-a716-446655440001
-
-## Critical
-
-- Always specify action: index, search, delete
-- index: text required
-- search: query required
-- delete: document_id required
-- Return operation results only. No commentary.
-- Include IDs, scores, metadata when relevant
-- Report errors concisely when fail
-- Semantic search: queries don't need exact matches
-
-## Description
-
-Handles vector DB: index, semantic search, delete. Auto-generates embeddings.
-
-[EXAMPLES]
-✅ Use for: Indexing, semantic search, document metadata
-❌ Don't use: File system (use OS or Coding agent)
-
-## AdvanceDescription
-
-- Purpose: Vector DB operations (index, search, delete)
-- Tool: vector_db (auto embedding generation)
-- Capabilities: Index with metadata; semantic search; delete; filter by metadata; top_k
-- Embeddings: Auto-generated. Model stored in metadata as _embedding_model
-- Search: Semantic (meaning, not exact match). Results by similarity.
-- Integration: Sub-agent when vector operations needed
-
-## Troubleshooting
-
-- action required: Specify index, search, or delete
-- text required: For index
-- query required: For search
-- document_id required: For delete
-- failed to generate embedding: Check embedding config
-- no results: Adjust top_k, filters, or query
-- Common: Missing action; wrong params; expecting exact match
-- Best: Specify action first; include metadata; descriptive queries; store IDs for deletion
diff --git a/src/agents/prompts/files/system-agents/web.md b/src/agents/prompts/files/system-agents/web.md
index fb4efa3..03ae888 100644
--- a/src/agents/prompts/files/system-agents/web.md
+++ b/src/agents/prompts/files/system-agents/web.md
@@ -93,7 +93,7 @@ Web navigation and content. 4 actions: navigate, click, get_content (when reques
 
 ## AdvanceDescription
 
-- Purpose: Web navigation and content via headless browser
+- Purpose: Web navigation and content via browser sessions (headless by default)
 - Tool: web_browser (navigate, click, get_content, save_content)
 - Capabilities: Navigate; click by selector; pull content; save to file; persistent context
 - Content: save_content = default. get_content = explicit request only. Report path.
diff --git a/src/agents/system/saVector.go b/src/agents/system/saVector.go
deleted file mode 100644
index 00da118..0000000
--- a/src/agents/system/saVector.go
+++ /dev/null
@@ -1,16 +0,0 @@
-package system
-
-// VectorAgentTemplate defines the system agent template for vector database operations.
-//
-// This agent handles vector database tasks including indexing documents, performing
-// semantic search, and deleting documents. It specializes in vector operations
-// and provides guidance on how to structure vector database requests.
-
-// CreateVectorAgentTemplate creates the template for vector database operations agent.
-func CreateVectorAgentTemplate() *SystemAgentTemplate {
-	template, err := LoadAgentTemplateFromMarkdown("vector", AgentNameSystemVector, TraceVector)
-	if err != nil {
-		panic(err)
-	}
-	return template
-}
diff --git a/src/agents/systemAgentConstructors.go b/src/agents/systemAgentConstructors.go
index 10fa466..aebfae0 100644
--- a/src/agents/systemAgentConstructors.go
+++ b/src/agents/systemAgentConstructors.go
@@ -10,7 +10,6 @@ import (
 	"github.com/thinktwiceco/agent-forge/src/tools/fs"
 	"github.com/thinktwiceco/agent-forge/src/tools/git"
 	imagetool "github.com/thinktwiceco/agent-forge/src/tools/image"
-	"github.com/thinktwiceco/agent-forge/src/tools/vector"
 	"github.com/thinktwiceco/agent-forge/src/tools/web"
 )
 
@@ -82,19 +81,6 @@ func ReasoningAgent(llmEngine llms.LLMEngine) core.SubAgent {
 	return agent.AgentAsSubAgent()
 }
 
-// VectorAgent creates a vector database operations agent.
-func VectorAgent(llmEngine llms.LLMEngine, vectorDB core.VectorDB, embeddingGenerator core.EmbeddingGenerator) core.SubAgent {
-	template := system.CreateVectorAgentTemplate()
-	config := systemConfigToAgentConfig(template.ToConfig(llmEngine))
-
-	// Add vector tool
-	vectorTool := vector.NewVectorTool(vectorDB, embeddingGenerator)
-	config.Tools = []llms.Tool{vectorTool}
-
-	agent := NewAgent(&config)
-	return agent.AgentAsSubAgent()
-}
-
 // VisionAgent creates a vision agent that loads images and answers visual questions.
 // The llmEngine must be backed by a vision-capable model (e.g. gpt-4o).
 func VisionAgent(llmEngine llms.LLMEngine, workingDir string) core.SubAgent {
diff --git a/src/agents/system_agents_test.go b/src/agents/system_agents_test.go
index 4132fdc..b351af0 100644
--- a/src/agents/system_agents_test.go
+++ b/src/agents/system_agents_test.go
@@ -121,24 +121,6 @@ func TestReasoningAgent_Constructor(t *testing.T) {
 	}
 }
 
-func TestVectorAgent_Constructor(t *testing.T) {
-	mockLLM := mocks.NewMockLLMEngine()
-	// Pass nil for dependencies as we are testing constructor logic mainly
-	agent := VectorAgent(mockLLM, nil, nil)
-
-	if agent == nil {
-		t.Fatal("VectorAgent returned nil")
-	}
-
-	if agent.Name() != AgentNameSystemVector {
-		t.Errorf("Expected name %s, got %s", AgentNameSystemVector, agent.Name())
-	}
-
-	if agent.BasicDescription() == "" {
-		t.Error("BasicDescription should not be empty")
-	}
-}
-
 func TestSystemAgentTemplate_Methods(t *testing.T) {
 	tmpl, err := system.NewSystemAgentTemplate("test", "trace")
 	if err != nil {
diff --git a/src/builder/subagents.go b/src/builder/subagents.go
index 7890ced..1d3fa39 100644
--- a/src/builder/subagents.go
+++ b/src/builder/subagents.go
@@ -16,7 +16,6 @@ const (
 	CODING_AGENT    Subagent = "coding"
 	OS_AGENT        Subagent = "os"
 	WEB_AGENT       Subagent = "web"
-	VECTOR_DB_AGENT Subagent = "vector"
 	VISION_AGENT    Subagent = "vision"
 )
 
@@ -37,11 +36,6 @@ func (s Subagent) getSubagent(
 		return agents.OsAgent(llmEngine, workingDir), nil
 	case WEB_AGENT:
 		return agents.WebAgent(llmEngine, workingDir), nil
-	case VECTOR_DB_AGENT:
-		if vectorDB == nil || embeddingGenerator == nil {
-			return nil, fmt.Errorf("vectorDB and embeddingGenerator are required for vector DB subagent")
-		}
-		return agents.VectorAgent(llmEngine, vectorDB, embeddingGenerator), nil
 	case VISION_AGENT:
 		return agents.VisionAgent(llmEngine, workingDir), nil
 	}
diff --git a/src/builder/tools.go b/src/builder/tools.go
index 8605e68..44b2045 100644
--- a/src/builder/tools.go
+++ b/src/builder/tools.go
@@ -11,7 +11,7 @@ import (
 	"github.com/thinktwiceco/agent-forge/src/tools/fs"
 	"github.com/thinktwiceco/agent-forge/src/tools/git"
 	"github.com/thinktwiceco/agent-forge/src/tools/postgres"
-	"github.com/thinktwiceco/agent-forge/src/tools/vector"
+	"github.com/thinktwiceco/agent-forge/src/tools/update"
 	"github.com/thinktwiceco/agent-forge/src/tools/web"
 	"gopkg.in/yaml.v3"
 )
@@ -60,10 +60,10 @@ func (t *Tool) UnmarshalYAML(value *yaml.Node) error {
 const (
 	FILE_SYSTEM_TOOL = "fs"
 	WEB_BROWSER_TOOL = "web"
-	VECTOR_DB_TOOL   = "vector"
 	GIT_TOOL         = "git"
 	POSTGRES_TOOL    = "postgres"
 	API_TOOL         = "api"
+	UPDATE_TOOL      = "update"
 )
 
 func (t *Tool) getTool(
@@ -82,11 +82,6 @@ func (t *Tool) getTool(
 			return nil, fmt.Errorf("working_dir is required for web tool")
 		}
 		return web.NewWebTool(filepath.Join(workingDir, "web")), nil
-	case VECTOR_DB_TOOL:
-		if vectorDB == nil || embeddingGenerator == nil {
-			return nil, fmt.Errorf("vectorDB and embeddingGenerator are required for vector DB tool")
-		}
-		return vector.NewVectorTool(vectorDB, embeddingGenerator), nil
 	case GIT_TOOL:
 		if workingDir == "" {
 			return nil, fmt.Errorf("working_dir is required for git tool")
@@ -151,6 +146,11 @@ func (t *Tool) getTool(
 		}
 
 		return api.NewApiTool(t.Name, endpoints, headers), nil
+	case UPDATE_TOOL:
+		if workingDir == "" {
+			return nil, fmt.Errorf("working_dir is required for update tool")
+		}
+		return update.NewUpdateTool(workingDir), nil
 	}
 	return nil, fmt.Errorf("invalid tool: %s", t.Name)
 }
diff --git a/src/tools/fs/actGrepFallback.go b/src/tools/fs/actGrepFallback.go
index 8808037..a971c5e 100644
--- a/src/tools/fs/actGrepFallback.go
+++ b/src/tools/fs/actGrepFallback.go
@@ -100,6 +100,7 @@ func (fs *Fs) grepFallback(relativePath, validatedPath, pattern string, flags []
 		if !hasRecursiveFlag(grepFlags) {
 			grepFlags = append([]string{"-r"}, grepFlags...)
 		}
+		grepFlags = append(grepFlags, "--exclude=.env", "--exclude=.env.*", "--exclude=*.env")
 	}
 
 	args := append(grepFlags, pattern, validatedPath)
diff --git a/src/tools/fs/actList.go b/src/tools/fs/actList.go
index 024c891..5b70d77 100644
--- a/src/tools/fs/actList.go
+++ b/src/tools/fs/actList.go
@@ -37,6 +37,10 @@ func (fs *Fs) listFiles(path string) (string, error) {
 	// Build file entries list
 	fileEntries := make([]fileEntry, 0, len(entries))
 	for _, entry := range entries {
+		if !entry.IsDir() && isEnvFilePath(entry.Name()) {
+			continue
+		}
+
 		info, err := entry.Info()
 		if err != nil {
 			// Skip entries we can't get info for
diff --git a/src/tools/fs/actRipgrep.go b/src/tools/fs/actRipgrep.go
index 9353756..593e9d9 100644
--- a/src/tools/fs/actRipgrep.go
+++ b/src/tools/fs/actRipgrep.go
@@ -3,6 +3,7 @@ package fs
 import (
 	"bytes"
 	"fmt"
+	"os"
 	"os/exec"
 	"strings"
 )
@@ -30,6 +31,10 @@ func (fs *Fs) ripgrep(path, pattern string, flags []string, offset, headLimit in
 		args = append(args, flags...)
 	}
 
+	if info, err := os.Stat(validatedPath); err == nil && info.IsDir() {
+		args = append(args, "--glob=!.env", "--glob=!.env.*", "--glob=!*.env")
+	}
+
 	// Add pattern
 	args = append(args, pattern)
 
diff --git a/src/tools/fs/tool_test.go b/src/tools/fs/tool_test.go
index 486b980..7fc6d7f 100644
--- a/src/tools/fs/tool_test.go
+++ b/src/tools/fs/tool_test.go
@@ -118,7 +118,61 @@ func TestFsTool_Integration(t *testing.T) {
 		}
 	})
 
-	// 8. Ripgrep Search
+	// 8. Block .env file access
+	t.Run("block_env_files", func(t *testing.T) {
+		if err := os.WriteFile(filepath.Join(tmpDir, ".env"), []byte("SECRET_KEY=test-secret"), 0644); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(tmpDir, "config.env"), []byte("API_KEY=test-key"), 0644); err != nil {
+			t.Fatal(err)
+		}
+
+		readEnv := tool.Call(nil, map[string]any{
+			"operation": "read",
+			"path":      ".env",
+		})
+		if readEnv.Success() {
+			t.Error("read should reject .env files")
+		}
+
+		writeEnv := tool.Call(nil, map[string]any{
+			"operation": "write",
+			"path":      ".env.local",
+			"content":   "TOKEN=blocked",
+		})
+		if writeEnv.Success() {
+			t.Error("write should reject .env.* files")
+		}
+
+		infoEnv := tool.Call(nil, map[string]any{
+			"operation": "get_file_info",
+			"path":      "config.env",
+		})
+		if infoEnv.Success() {
+			t.Error("get_file_info should reject *.env files")
+		}
+
+		deleteEnv := tool.Call(nil, map[string]any{
+			"operation": "delete",
+			"path":      ".env",
+		})
+		if deleteEnv.Success() {
+			t.Error("delete should reject .env files")
+		}
+
+		listResult := tool.Call(nil, map[string]any{
+			"operation": "list",
+			"path":      ".",
+		})
+		if !listResult.Success() {
+			t.Fatalf("list failed: %s", listResult.Error())
+		}
+		if strings.Contains(listResult.Data(), ".env") || strings.Contains(listResult.Data(), "config.env") {
+			t.Errorf("list should not expose .env files, got: %s", listResult.Data())
+		}
+	})
+
+	// 9. Ripgrep Search
 	t.Run("ripgrep", func(t *testing.T) {
 		// Create test files
 		testContent1 := "This is a test file\nWith multiple lines\nContaining searchable content"
@@ -195,7 +249,29 @@ func TestFsTool_Integration(t *testing.T) {
 		}
 	})
 
-	// 9. GrepLogs - unavailable when AF_LOG_FILE not set
+	// 10. Ripgrep should exclude .env files
+	t.Run("ripgrep_excludes_env_files", func(t *testing.T) {
+		result := tool.Call(nil, map[string]any{
+			"operation": "ripgrep",
+			"path":      ".",
+			"pattern":   "test-secret|test-key",
+			"flags":     []interface{}{"-n"},
+		})
+
+		if !result.Success() && strings.Contains(result.Error(), "not installed") {
+			t.Skip("ripgrep not installed, skipping test")
+		}
+
+		if !result.Success() {
+			t.Fatalf("ripgrep failed: %s", result.Error())
+		}
+
+		if strings.Contains(result.Data(), ".env") || strings.Contains(result.Data(), "config.env") {
+			t.Errorf("ripgrep should exclude .env files, got: %s", result.Data())
+		}
+	})
+
+	// 11. GrepLogs - unavailable when AF_LOG_FILE not set
 	t.Run("grep_logs_unavailable", func(t *testing.T) {
 		// Ensure AF_LOG_FILE is unset
 		origVal := os.Getenv("AF_LOG_FILE")
@@ -219,7 +295,7 @@ func TestFsTool_Integration(t *testing.T) {
 		}
 	})
 
-	// 10. GrepLogs - works when AF_LOG_FILE is set
+	// 12. GrepLogs - works when AF_LOG_FILE is set
 	t.Run("grep_logs_available", func(t *testing.T) {
 		// Create a temp log file
 		logFile, err := os.CreateTemp("", "grep-logs-test-*.log")
diff --git a/src/tools/fs/validate.go b/src/tools/fs/validate.go
index 1be84ca..12dcc03 100644
--- a/src/tools/fs/validate.go
+++ b/src/tools/fs/validate.go
@@ -16,13 +16,32 @@ var textExtensions = map[string]bool{
 	".rb": true, ".rs": true, ".java": true, ".kt": true, ".c": true,
 	".h": true, ".cpp": true, ".hpp": true, ".cs": true, ".php": true,
 	".sh": true, ".bash": true, ".zsh": true, ".sql": true, ".csv": true,
-	".toml": true, ".ini": true, ".cfg": true, ".conf": true, ".env": true,
+	".toml": true, ".ini": true, ".cfg": true, ".conf": true,
 	".log": true, ".lock": true, ".sum": true, ".mod": true,
 }
 
+func isEnvFilePath(filePath string) bool {
+	base := strings.ToLower(filepath.Base(filepath.Clean(filePath)))
+	ext := strings.ToLower(filepath.Ext(base))
+
+	return base == ".env" || strings.HasPrefix(base, ".env.") || ext == ".env"
+}
+
+func (fs *Fs) validateNoEnvPath(filePath string) error {
+	if isEnvFilePath(filePath) {
+		return fmt.Errorf("access to .env files is not allowed: %s", filePath)
+	}
+
+	return nil
+}
+
 // validatePath ensures that the given file path stays within the root directory.
 // It returns the validated absolute path or an error if the path escapes the root.
 func (fs *Fs) validatePath(filePath string) (string, error) {
+	if err := fs.validateNoEnvPath(filePath); err != nil {
+		return "", err
+	}
+
 	// Get absolute path of root
 	absRoot, err := filepath.Abs(fs.dir)
 	if err != nil {
diff --git a/src/tools/update/tool.go b/src/tools/update/tool.go
new file mode 100644
index 0000000..e50780a
--- /dev/null
+++ b/src/tools/update/tool.go
@@ -0,0 +1,134 @@
+package update
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+
+	"github.com/thinktwiceco/agent-forge/src/core"
+	"github.com/thinktwiceco/agent-forge/src/llms"
+)
+
+const updateScriptName = "update-release.sh"
+
+// Update runs the installation's update-release.sh script from the agent root.
+type Update struct {
+	dir string
+}
+
+// NewUpdateTool creates a built-in tool that executes update-release.sh in the
+// agent working directory root.
+func NewUpdateTool(dir string) llms.Tool {
+	updateTool := &Update{dir: dir}
+
+	return &core.Tool{
+		Name:        "update",
+		Description: "Run the root update-release.sh script to update the current agent installation.",
+		AdvanceDesc: `Advanced Details:
+- Parameters: none
+- Behavior:
+  * Resolves exactly ./update-release.sh in the agent root
+  * Refuses to run if the script is missing or is not a regular file
+  * Executes the script with bash from the agent root
+  * Returns captured stdout and stderr so the caller can inspect update results`,
+		TroubleshootingInfo: `Troubleshooting:
+- "update-release.sh not found": The agent installation does not contain the update script in its root directory
+- "update-release.sh is not a regular file": The path exists but is not a normal file
+- "bash is required": Install bash or ensure it is available in PATH
+- Non-zero exit: Inspect stdout/stderr returned by the tool for the underlying update error`,
+		Handler: func(agentContext map[string]any, args map[string]any) llms.ToolReturn {
+			result, err := updateTool.run()
+			if err != nil {
+				return core.NewErrorResponse(err.Error())
+			}
+			return core.NewSuccessResponse(result)
+		},
+	}
+}
+
+func (u *Update) validateScriptPath() (string, error) {
+	absRoot, err := filepath.Abs(u.dir)
+	if err != nil {
+		return "", fmt.Errorf("invalid root directory: %w", err)
+	}
+
+	scriptPath := filepath.Join(absRoot, updateScriptName)
+	absScriptPath, err := filepath.Abs(scriptPath)
+	if err != nil {
+		return "", fmt.Errorf("invalid update script path: %w", err)
+	}
+
+	relPath, err := filepath.Rel(absRoot, absScriptPath)
+	if err != nil {
+		return "", fmt.Errorf("path validation failed: %w", err)
+	}
+	if len(relPath) >= 2 && relPath[:2] == ".." {
+		return "", fmt.Errorf("path traversal detected while resolving %s", updateScriptName)
+	}
+
+	info, err := os.Stat(absScriptPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", fmt.Errorf("%s not found in agent root: %s", updateScriptName, absRoot)
+		}
+		return "", fmt.Errorf("failed to stat %s: %w", updateScriptName, err)
+	}
+	if !info.Mode().IsRegular() {
+		return "", fmt.Errorf("%s is not a regular file", updateScriptName)
+	}
+
+	return absScriptPath, nil
+}
+
+func (u *Update) run() (string, error) {
+	absRoot, err := filepath.Abs(u.dir)
+	if err != nil {
+		return "", fmt.Errorf("invalid root directory: %w", err)
+	}
+
+	scriptPath, err := u.validateScriptPath()
+	if err != nil {
+		return "", err
+	}
+
+	if _, err := exec.LookPath("bash"); err != nil {
+		return "", fmt.Errorf("bash is required to run %s: %w", updateScriptName, err)
+	}
+
+	cmd := exec.Command("bash", scriptPath)
+	cmd.Dir = absRoot
+
+	var stdout, stderr strings.Builder
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	err = cmd.Run()
+	stdoutStr := strings.TrimSpace(stdout.String())
+	stderrStr := strings.TrimSpace(stderr.String())
+
+	if err != nil {
+		var details []string
+		if stdoutStr != "" {
+			details = append(details, "stdout:\n"+stdoutStr)
+		}
+		if stderrStr != "" {
+			details = append(details, "stderr:\n"+stderrStr)
+		}
+		if len(details) == 0 {
+			return "", fmt.Errorf("%s failed: %w", updateScriptName, err)
+		}
+		return "", fmt.Errorf("%s failed: %w\n\n%s", updateScriptName, err, strings.Join(details, "\n\n"))
+	}
+
+	parts := []string{fmt.Sprintf("Update script completed successfully: %s", updateScriptName)}
+	if stdoutStr != "" {
+		parts = append(parts, "stdout:\n"+stdoutStr)
+	}
+	if stderrStr != "" {
+		parts = append(parts, "stderr:\n"+stderrStr)
+	}
+
+	return strings.Join(parts, "\n\n"), nil
+}
diff --git a/src/tools/update/tool_test.go b/src/tools/update/tool_test.go
new file mode 100644
index 0000000..153e103
--- /dev/null
+++ b/src/tools/update/tool_test.go
@@ -0,0 +1,71 @@
+package update
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestUpdateTool_Success(t *testing.T) {
+	tmpDir := t.TempDir()
+	scriptPath := filepath.Join(tmpDir, updateScriptName)
+
+	script := "#!/bin/bash\nprintf 'updated successfully\\n'\nprintf 'warning stream\\n' >&2\n"
+	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
+		t.Fatalf("failed to write update script: %v", err)
+	}
+
+	tool := NewUpdateTool(tmpDir)
+	result := tool.Call(nil, nil)
+
+	if !result.Success() {
+		t.Fatalf("expected success, got error: %s", result.Error())
+	}
+	if !strings.Contains(result.Data(), "updated successfully") {
+		t.Fatalf("expected stdout in result data, got: %s", result.Data())
+	}
+	if !strings.Contains(result.Data(), "warning stream") {
+		t.Fatalf("expected stderr in result data, got: %s", result.Data())
+	}
+}
+
+func TestUpdateTool_MissingScript(t *testing.T) {
+	tmpDir := t.TempDir()
+
+	tool := NewUpdateTool(tmpDir)
+	result := tool.Call(nil, nil)
+
+	if result.Success() {
+		t.Fatal("expected failure when update script is missing")
+	}
+	if !strings.Contains(result.Error(), "not found") {
+		t.Fatalf("expected missing script error, got: %s", result.Error())
+	}
+}
+
+func TestUpdateTool_NonZeroExit(t *testing.T) {
+	tmpDir := t.TempDir()
+	scriptPath := filepath.Join(tmpDir, updateScriptName)
+
+	script := "#!/bin/bash\nprintf 'partial output\\n'\nprintf 'update failed\\n' >&2\nexit 7\n"
+	if err := os.WriteFile(scriptPath, []byte(script), 0755); err != nil {
+		t.Fatalf("failed to write update script: %v", err)
+	}
+
+	tool := NewUpdateTool(tmpDir)
+	result := tool.Call(nil, nil)
+
+	if result.Success() {
+		t.Fatal("expected failure for non-zero exit")
+	}
+	if !strings.Contains(result.Error(), "failed") {
+		t.Fatalf("expected failure message, got: %s", result.Error())
+	}
+	if !strings.Contains(result.Error(), "partial output") {
+		t.Fatalf("expected stdout in failure message, got: %s", result.Error())
+	}
+	if !strings.Contains(result.Error(), "update failed") {
+		t.Fatalf("expected stderr in failure message, got: %s", result.Error())
+	}
+}
diff --git a/src/tools/vector/actDelete.go b/src/tools/vector/actDelete.go
deleted file mode 100644
index 72b03f2..0000000
--- a/src/tools/vector/actDelete.go
+++ /dev/null
@@ -1,29 +0,0 @@
-package vector
-
-import (
-	"fmt"
-
-	"github.com/thinktwiceco/agent-forge/src/core"
-	"github.com/thinktwiceco/agent-forge/src/llms"
-)
-
-// delete handles the delete action for the vector tool.
-func (v *Vector) delete(args map[string]any) llms.ToolReturn {
-	// Extract document_id (required)
-	documentID, ok := args["document_id"].(string)
-	if !ok || documentID == "" {
-		return core.NewErrorResponse("document_id parameter is required for delete action and must be a non-empty string")
-	}
-
-	if v.vectorDB == nil {
-		return core.NewErrorResponse("vector database not configured for vector tool")
-	}
-
-	// Delete the document
-	err := v.vectorDB.Delete(documentID)
-	if err != nil {
-		return core.NewErrorResponse(fmt.Sprintf("failed to delete document: %v", err))
-	}
-
-	return core.NewSuccessResponse(fmt.Sprintf("Document %s deleted successfully", documentID))
-}
diff --git a/src/tools/vector/actIndex.go b/src/tools/vector/actIndex.go
deleted file mode 100644
index 48019e1..0000000
--- a/src/tools/vector/actIndex.go
+++ /dev/null
@@ -1,102 +0,0 @@
-package vector
-
-import (
-	"fmt"
-
-	"github.com/google/uuid"
-	"github.com/thinktwiceco/agent-forge/src/core"
-	"github.com/thinktwiceco/agent-forge/src/llms"
-)
-
-// index handles the index action for the vector tool.
-func (v *Vector) index(args map[string]any) llms.ToolReturn {
-	// Extract text (required)
-	text, ok := args["text"].(string)
-	if !ok || text == "" {
-		return core.NewErrorResponse("text parameter is required for index action and must be a non-empty string")
-	}
-
-	// Extract metadata (optional)
-	var metadata map[string]any
-	if md, ok := args["metadata"]; ok {
-		metadata, ok = md.(map[string]any)
-		if !ok {
-			return core.NewErrorResponse("metadata parameter must be an object")
-		}
-	} else {
-		metadata = make(map[string]any)
-	}
-
-	// Extract or generate document_id (optional)
-	documentID, ok := args["document_id"].(string)
-	if !ok || documentID == "" {
-		documentID = uuid.New().String()
-	}
-
-	// Chunk the text if it's too large
-	chunks := chunkText(text)
-
-	if len(chunks) == 1 {
-		// Single chunk - index normally
-		if v.embeddingGenerator == nil {
-			return core.NewErrorResponse("embedding generator not configured for vector tool")
-		}
-		embedding, modelName, err := v.embeddingGenerator.GenerateEmbedding(text)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to generate embedding: %v", err))
-		}
-
-		// Add embedding model to metadata
-		metadata["_embedding_model"] = modelName
-
-		// Index the document
-		if v.vectorDB == nil {
-			return core.NewErrorResponse("vector database not configured for vector tool")
-		}
-		resultID, err := v.vectorDB.Index(embedding, text, metadata, modelName)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to index document: %v", err))
-		}
-
-		// Use the returned ID if provided, otherwise use the one we generated
-		if resultID != "" {
-			documentID = resultID
-		}
-
-		return core.NewSuccessResponse(fmt.Sprintf("Document indexed successfully with ID: %s", documentID))
-	}
-
-	// Multiple chunks - index each chunk with linking metadata
-	var indexedIDs []string
-	for i, chunk := range chunks {
-		chunkMetadata := make(map[string]any)
-		// Copy original metadata
-		for k, v := range metadata {
-			chunkMetadata[k] = v
-		}
-		// Add chunk-specific metadata
-		chunkMetadata["_parent_document_id"] = documentID
-		chunkMetadata["_chunk_index"] = i
-		chunkMetadata["_total_chunks"] = len(chunks)
-
-		embedding, modelName, err := v.embeddingGenerator.GenerateEmbedding(chunk)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to generate embedding for chunk %d/%d: %v", i+1, len(chunks), err))
-		}
-
-		chunkMetadata["_embedding_model"] = modelName
-
-		chunkID := fmt.Sprintf("%s_chunk_%d", documentID, i)
-		resultID, err := v.vectorDB.Index(embedding, chunk, chunkMetadata, modelName)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to index chunk %d/%d: %v", i+1, len(chunks), err))
-		}
-
-		if resultID != "" {
-			chunkID = resultID
-		}
-		indexedIDs = append(indexedIDs, chunkID)
-	}
-
-	return core.NewSuccessResponse(fmt.Sprintf("Document indexed successfully as %d chunks with parent ID: %s (chunk IDs: %v)", len(chunks), documentID, indexedIDs))
-}
diff --git a/src/tools/vector/actIndexFile.go b/src/tools/vector/actIndexFile.go
deleted file mode 100644
index 1bca2e5..0000000
--- a/src/tools/vector/actIndexFile.go
+++ /dev/null
@@ -1,123 +0,0 @@
-package vector
-
-import (
-	"fmt"
-	"os"
-
-	"github.com/google/uuid"
-	"github.com/thinktwiceco/agent-forge/src/core"
-	"github.com/thinktwiceco/agent-forge/src/llms"
-)
-
-// indexFile handles the indexFile action for the vector tool.
-// It reads content from a file path and indexes it.
-func (v *Vector) indexFile(args map[string]any) llms.ToolReturn {
-	// Extract file_path (required)
-	filePath, ok := args["file_path"].(string)
-	if !ok || filePath == "" {
-		return core.NewErrorResponse("file_path parameter is required for indexFile action and must be a non-empty string")
-	}
-
-	// Read file content
-	content, err := os.ReadFile(filePath)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return core.NewErrorResponse(fmt.Sprintf("file not found: %s", filePath))
-		}
-		return core.NewErrorResponse(fmt.Sprintf("failed to read file '%s': %v", filePath, err))
-	}
-
-	text := string(content)
-	if text == "" {
-		return core.NewErrorResponse(fmt.Sprintf("file '%s' is empty", filePath))
-	}
-
-	// Extract metadata (optional)
-	var metadata map[string]any
-	if md, ok := args["metadata"]; ok {
-		metadata, ok = md.(map[string]any)
-		if !ok {
-			return core.NewErrorResponse("metadata parameter must be an object")
-		}
-	} else {
-		metadata = make(map[string]any)
-	}
-
-	// Add file path to metadata
-	metadata["_file_path"] = filePath
-
-	// Extract or generate document_id (optional)
-	documentID, ok := args["document_id"].(string)
-	if !ok || documentID == "" {
-		documentID = uuid.New().String()
-	}
-
-	if v.embeddingGenerator == nil {
-		return core.NewErrorResponse("embedding generator not configured for vector tool")
-	}
-
-	if v.vectorDB == nil {
-		return core.NewErrorResponse("vector database not configured for vector tool")
-	}
-
-	// Chunk the text if it's too large
-	chunks := chunkText(text)
-
-	if len(chunks) == 1 {
-		// Single chunk - index normally
-		embedding, modelName, err := v.embeddingGenerator.GenerateEmbedding(text)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to generate embedding: %v", err))
-		}
-
-		// Add embedding model to metadata
-		metadata["_embedding_model"] = modelName
-
-		// Index the document
-		resultID, err := v.vectorDB.Index(embedding, text, metadata, modelName)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to index document: %v", err))
-		}
-
-		// Use the returned ID if provided, otherwise use the one we generated
-		if resultID != "" {
-			documentID = resultID
-		}
-
-		return core.NewSuccessResponse(fmt.Sprintf("Document from file '%s' indexed successfully with ID: %s", filePath, documentID))
-	}
-
-	// Multiple chunks - index each chunk with linking metadata
-	var indexedIDs []string
-	for i, chunk := range chunks {
-		chunkMetadata := make(map[string]any)
-		// Copy original metadata
-		for k, v := range metadata {
-			chunkMetadata[k] = v
-		}
-		// Add chunk-specific metadata
-		chunkMetadata["_parent_document_id"] = documentID
-		chunkMetadata["_chunk_index"] = i
-		chunkMetadata["_total_chunks"] = len(chunks)
-
-		embedding, modelName, err := v.embeddingGenerator.GenerateEmbedding(chunk)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to generate embedding for chunk %d/%d: %v", i+1, len(chunks), err))
-		}
-
-		chunkMetadata["_embedding_model"] = modelName
-
-		chunkID := fmt.Sprintf("%s_chunk_%d", documentID, i)
-		resultID, err := v.vectorDB.Index(embedding, chunk, chunkMetadata, modelName)
-		if err != nil {
-			return core.NewErrorResponse(fmt.Sprintf("failed to index chunk %d/%d: %v", i+1, len(chunks), err))
-		}
-
-		if resultID != "" {
-			chunkID = resultID
-		}
-		indexedIDs = append(indexedIDs, chunkID)
-	}
-
-	return core.NewSuccessResponse(fmt.Sprintf("Document from file '%s' indexed successfully as %d chunks with parent ID: %s (chunk IDs: %v)", filePath, len(chunks), documentID, indexedIDs))
-}
diff --git a/src/tools/vector/actListDocuments.go b/src/tools/vector/actListDocuments.go
deleted file mode 100644
index 1352cbf..0000000
--- a/src/tools/vector/actListDocuments.go
+++ /dev/null
@@ -1,94 +0,0 @@
-package vector
-
-import (
-	"encoding/json"
-	"fmt"
-
-	"github.com/thinktwiceco/agent-forge/src/core"
-	"github.com/thinktwiceco/agent-forge/src/llms"
-)
-
-// listDocumentsResponse represents the response structure for listDocuments action.
-type listDocumentsResponse struct {
-	Documents []core.DocumentSummary `json:"documents"`
-	Total     int                    `json:"total"`
-}
-
-// listDocuments handles the listDocuments action for the vector tool.
-func (v *Vector) listDocuments(args map[string]any) llms.ToolReturn {
-	// Extract offset (optional, default: 0)
-	offset := 0
-	if off, ok := args["offset"]; ok {
-		switch v := off.(type) {
-		case float64:
-			offset = int(v)
-		case int:
-			offset = v
-		case int64:
-			offset = int(v)
-		default:
-			return core.NewErrorResponse("offset parameter must be a number")
-		}
-		if offset < 0 {
-			return core.NewErrorResponse("offset must be greater than or equal to 0")
-		}
-	}
-
-	// Extract limit (optional, default: 10)
-	limit := 10
-	if lim, ok := args["limit"]; ok {
-		switch v := lim.(type) {
-		case float64:
-			limit = int(v)
-		case int:
-			limit = v
-		case int64:
-			limit = int(v)
-		default:
-			return core.NewErrorResponse("limit parameter must be a number")
-		}
-		if limit <= 0 {
-			return core.NewErrorResponse("limit must be greater than 0")
-		}
-	}
-
-	// Extract filters (optional)
-	var filters map[string]any
-	if f, ok := args["filters"]; ok {
-		filters, ok = f.(map[string]any)
-		if !ok {
-			return core.NewErrorResponse("filters parameter must be an object")
-		}
-	}
-
-	// Build ListOptions
-	opts := core.ListOptions{
-		Offset:  offset,
-		Limit:   limit,
-		Filters: filters,
-	}
-
-	if v.vectorDB == nil {
-		return core.NewErrorResponse("vector database not configured for vector tool")
-	}
-
-	// List documents
-	documents, total, err := v.vectorDB.ListDocuments(opts)
-	if err != nil {
-		return core.NewErrorResponse(fmt.Sprintf("failed to list documents: %v", err))
-	}
-
-	// Build response
-	response := listDocumentsResponse{
-		Documents: documents,
-		Total:     total,
-	}
-
-	// Format results as JSON
-	responseJSON, err := json.Marshal(response)
-	if err != nil {
-		return core.NewErrorResponse(fmt.Sprintf("failed to serialize list results: %v", err))
-	}
-
-	return core.NewSuccessResponse(string(responseJSON))
-}
diff --git a/src/tools/vector/actSearch.go b/src/tools/vector/actSearch.go
deleted file mode 100644
index d6692d2..0000000
--- a/src/tools/vector/actSearch.go
+++ /dev/null
@@ -1,71 +0,0 @@
-package vector
-
-import (
-	"encoding/json"
-	"fmt"
-
-	"github.com/thinktwiceco/agent-forge/src/core"
-	"github.com/thinktwiceco/agent-forge/src/llms"
-)
-
-// search handles the search action for the vector tool.
-func (v *Vector) search(args map[string]any) llms.ToolReturn {
-	// Extract query (required)
-	query, ok := args["query"].(string)
-	if !ok || query == "" {
-		return core.NewErrorResponse("query parameter is required for search action and must be a non-empty string")
-	}
-
-	// Extract top_k (optional, default: 10)
-	topK := 10
-	if tk, ok := args["top_k"]; ok {
-		switch v := tk.(type) {
-		case float64:
-			topK = int(v)
-		case int:
-			topK = v
-		case int64:
-			topK = int(v)
-		default:
-			return core.NewErrorResponse("top_k parameter must be a number")
-		}
-		if topK <= 0 {
-			return core.NewErrorResponse("top_k must be greater than 0")
-		}
-	}
-
-	// Extract filters (optional)
-	var filters map[string]any
-	if f, ok := args["filters"]; ok {
-		filters, ok = f.(map[string]any)
-		if !ok {
-			return core.NewErrorResponse("filters parameter must be an object")
-		}
-	}
-
-	// Generate embedding for query
-	if v.embeddingGenerator == nil {
-		return core.NewErrorResponse("embedding generator not configured for vector tool")
-	}
-	queryEmbedding, _, err := v.embeddingGenerator.GenerateEmbedding(query)
-	if err != nil {
-		return core.NewErrorResponse(fmt.Sprintf("failed to generate query embedding: %v", err))
-	}
-
-	// Perform search
-	if v.vectorDB == nil {
-		return core.NewErrorResponse("vector database not configured for vector tool")
-	}
-	results, err := v.vectorDB.Search(queryEmbedding, topK, filters)
-	if err != nil {
-		return core.NewErrorResponse(fmt.Sprintf("failed to search: %v", err))
-	}
-
-	// Format results as JSON
-	resultsJSON, err := json.Marshal(results)
-	if err != nil {
-		return core.NewErrorResponse(fmt.Sprintf("failed to serialize search results: %v", err))
-	}
-
-	return core.NewSuccessResponse(string(resultsJSON))
-}
diff --git a/src/tools/vector/chunking.go b/src/tools/vector/chunking.go
deleted file mode 100644
index b42a8bf..0000000
--- a/src/tools/vector/chunking.go
+++ /dev/null
@@ -1,79 +0,0 @@
-package vector
-
-import (
-	"strings"
-)
-
-const (
-	// maxTokensPerChunk is the maximum number of tokens per chunk.
-	// Using 7000 to leave margin below the 8192 token limit for text-embedding-3-small
-	maxTokensPerChunk = 7000
-
-	// charsPerToken is a conservative estimate: ~4 characters per token for English text
-	charsPerToken = 4
-
-	// maxCharsPerChunk is the maximum characters per chunk based on token limit
-	maxCharsPerChunk = maxTokensPerChunk * charsPerToken
-)
-
-// chunkText splits text into chunks that are within the token limit.
-// It attempts to split at sentence boundaries when possible.
-func chunkText(text string) []string {
-	if len(text) <= maxCharsPerChunk {
-		return []string{text}
-	}
-
-	var chunks []string
-	remaining := text
-
-	for len(remaining) > 0 {
-		if len(remaining) <= maxCharsPerChunk {
-			chunks = append(chunks, remaining)
-			break
-		}
-
-		// Try to find a good split point (sentence boundary)
-		chunk := remaining[:maxCharsPerChunk]
-
-		// Look for sentence endings within the last 20% of the chunk
-		searchStart := int(float64(len(chunk)) * 0.8)
-		bestSplit := len(chunk)
-
-		// Look for sentence endings (. ! ? followed by space or newline)
-		for i := searchStart; i < len(chunk); i++ {
-			char := chunk[i]
-			// Check if we're at a sentence boundary
-			if char == '.' || char == '!' || char == '?' {
-				// Check if followed by space/newline or if we're at the end
-				if i+1 >= len(chunk) {
-					bestSplit = i + 1
-					break
-				}
-				nextChar := chunk[i+1]
-				if nextChar == ' ' || nextChar == '\n' || nextChar == '\r' {
-					bestSplit = i + 1
-					break
-				}
-			}
-		}
-
-		// If no sentence boundary found, try paragraph boundary (double newline)
-		if bestSplit == len(chunk) {
-			lastNewline := strings.LastIndex(chunk[:bestSplit], "\n\n")
-			if lastNewline > searchStart {
-				bestSplit = lastNewline + 2
-			} else {
-				// Try single newline
-				lastNewline = strings.LastIndex(chunk[:bestSplit], "\n")
-				if lastNewline > searchStart {
-					bestSplit = lastNewline + 1
-				}
-			}
-		}
-
-		chunks = append(chunks, remaining[:bestSplit])
-		remaining = strings.TrimSpace(remaining[bestSplit:])
-	}
-
-	return chunks
-}
diff --git a/src/tools/vector/chunking_test.go b/src/tools/vector/chunking_test.go
deleted file mode 100644
index d543b33..0000000
--- a/src/tools/vector/chunking_test.go
+++ /dev/null
@@ -1,87 +0,0 @@
-package vector
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestChunkText(t *testing.T) {
-	// Create a long string for testing
-	shortText := "This is a short text."
-
-	// Create text exactly maxCharsPerChunk (assuming 1000 from default implementation, but checking constant is better)
-	// Since maxCharsPerChunk is unexported constant in chunking.go (and defined as 4000 usually?), verify via test behavior
-	// Assuming a large enough text to split.
-
-	// maxCharsPerChunk is 7000 * 4 = 28000
-	// We need > 28000 chars to trigger split
-	longParagraph := strings.Repeat("Word ", 6000) // 30000 chars
-
-	sentence1 := "This is the first sentence. "
-	sentence2 := "This is the second sentence. "
-
-	tests := []struct {
-		name      string
-		input     string
-		wantCount int // Minimum expected chunks
-	}{
-		{
-			name:      "short_text",
-			input:     shortText,
-			wantCount: 1,
-		},
-		{
-			name:      "long_text_split",
-			input:     longParagraph,
-			wantCount: 2, // Should be split at least once if limit < 5000
-		},
-		{
-			name:      "sentence_boundary",
-			input:     sentence1 + sentence2,
-			wantCount: 1, // Should fit if limit is high enough
-		},
-	}
-
-	// Double check maxCharsPerChunk is not exported. It is defined as constant in chunking.go
-	// We can trust the function to split correctly if input > limit.
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			chunks := chunkText(tt.input)
-			if len(chunks) < tt.wantCount {
-				t.Errorf("Expected at least %d chunks, got %d", tt.wantCount, len(chunks))
-			}
-
-			// Verify content is preserved
-			reconstructed := strings.Join(chunks, "")
-			// Note: chunkText might trim spaces, so exact reconstruction might fail if logic does trimming.
-			// Let's check length mostly matches
-			if len(reconstructed) > len(tt.input) {
-				t.Errorf("Reconstructed text longer than input")
-			}
-		})
-	}
-}
-
-func TestChunkText_SplittingLogic(t *testing.T) {
-	// Setup a string that MUST be split.
-	// To reliably test splitting without knowing constant, we can look at the code or assume standard.
-	// But `chunkText` logic is specific.
-	// Let's assume standard behavior: splits > maxChars.
-
-	// Since we can't change the constant easily, we just verify it produces valid chunks
-	input := strings.Repeat("A", 10000)
-	chunks := chunkText(input)
-
-	if len(chunks) <= 1 {
-		// If it wasn't split, maybe limit is huge?
-		// If so, pass, but usually it's ~4000.
-		_ = input // Assumption: 10000 chars should split if limit fits in 4000
-	}
-
-	for i, chunk := range chunks {
-		if len(chunk) == 0 {
-			t.Errorf("Chunk %d is empty", i)
-		}
-	}
-}
diff --git a/src/tools/vector/tool.go b/src/tools/vector/tool.go
deleted file mode 100644
index 4667c0f..0000000
--- a/src/tools/vector/tool.go
+++ /dev/null
@@ -1,166 +0,0 @@
-package vector
-
-import (
-	"fmt"
-
-	"github.com/thinktwiceco/agent-forge/src/core"
-	"github.com/thinktwiceco/agent-forge/src/llms"
-)
-
-// NewVectorTool creates a new vector database tool that allows indexing, searching, and deleting documents.
-//
-// The tool requires a VectorDB implementation for storage and an EmbeddingGenerator for creating embeddings.
-//
-// Available actions:
-//   - index: Index a document with text and optional metadata
-//   - indexFile: Index a document from a file path
-//   - search: Perform semantic search with optional filters
-//   - listDocuments: List documents with pagination and optional filters
-//   - delete: Delete a document by ID
-func NewVectorTool(vectorDB core.VectorDB, embeddingGenerator core.EmbeddingGenerator) llms.Tool {
-	v := &Vector{
-		vectorDB:           vectorDB,
-		embeddingGenerator: embeddingGenerator,
-	}
-
-	detailsAbout := func(item string) string {
-		switch item {
-		case "index":
-			return `index: Index a document with text content and optional metadata.
-- Required: text (string) — document text to embed and store
-- Optional: document_id (string) — custom ID; auto-generated UUID if omitted
-- Optional: metadata (object) — free-form key-value pairs stored alongside the document
-- The embedding model name is automatically stored in metadata as "_embedding_model"`
-		case "indexFile":
-			return `indexFile: Read a file and index its content as a document.
-- Required: file_path (string) — path to the file to read and index
-- Optional: document_id (string) — custom ID; auto-generated UUID if omitted
-- Optional: metadata (object) — free-form key-value pairs`
-		case "search":
-			return `search: Perform semantic search using a query string.
-- Required: query (string) — search query text
-- Optional: top_k (number, default 10) — number of results to return
-- Optional: filters (object) — exact-match metadata filters, e.g. {"category": "docs"}
-- Returns: results with text, metadata, and similarity scores (highest first)`
-		case "listDocuments":
-			return `listDocuments: List documents from the vector database with pagination.
-- Optional: offset (number, default 0) — number of documents to skip
-- Optional: limit (number, default 10) — maximum number of documents to return
-- Optional: filters (object) — exact-match metadata filters
-- Returns: documents with text, metadata, and total count`
-		case "delete":
-			return `delete: Remove a document from the vector database by its ID.
-- Required: document_id (string) — the ID of the document to delete`
-		default:
-			return fmt.Sprintf("Nothing to add about %s", item)
-		}
-	}
-
-	return &core.Tool{
-		Name:        "vector_db",
-		Description: "Index, search, and delete documents in a vector database using semantic search.",
-		AdvanceDesc: `Advanced Details:
-- Available actions: index, indexFile, search, listDocuments, delete
-  Use expand tool with details_about="<action>" for full parameter details on any action.
-- Common parameters:
-  * action (required): the action to perform
-- Behavior:
-  * Embeddings are generated automatically; model name is stored in metadata as "_embedding_model"
-  * search results are ordered by similarity score (highest first)
-  * Metadata filtering uses exact match on key-value pairs`,
-		DetailsAboutFunc: detailsAbout,
-		TroubleshootingInfo: `Troubleshooting:
-- If index fails: Ensure text parameter is provided and non-empty
-- If indexFile fails: Ensure file_path parameter is provided, file exists, and is readable
-- If search fails: Ensure query parameter is provided and non-empty
-- If listDocuments fails: Ensure offset and limit are non-negative numbers
-- If delete fails: Ensure document_id exists in the database
-- If embedding generation fails: Check that the embedding generator is properly configured
-- If no results found: Try adjusting top_k/limit or removing filters
-- Ensure action parameter is exactly one of: index, indexFile, search, listDocuments, delete`,
-		Parameters: []core.Parameter{
-			{
-				Name:        "action",
-				Type:        "string",
-				Description: "The action to perform: 'index', 'indexFile', 'search', 'listDocuments', or 'delete'",
-				Required:    true,
-				Validator:   validateAction,
-			},
-			{
-				Name:        "text",
-				Type:        "string",
-				Description: "The document text to index (required for 'index' action)",
-				Required:    false,
-			},
-			{
-				Name:        "file_path",
-				Type:        "string",
-				Description: "The file path to read and index (required for 'indexFile' action)",
-				Required:    false,
-			},
-			{
-				Name:        "query",
-				Type:        "string",
-				Description: "The search query text (required for 'search' action)",
-				Required:    false,
-			},
-			{
-				Name:        "metadata",
-				Type:        "object",
-				Description: "Free-form key-value pairs for document metadata (optional)",
-				Required:    false,
-			},
-			{
-				Name:        "document_id",
-				Type:        "string",
-				Description: "Document ID - auto-generated UUID if not provided for 'index'/'indexFile', required for 'delete'",
-				Required:    false,
-			},
-			{
-				Name:        "top_k",
-				Type:        "number",
-				Description: "Number of results to return for search (default: 10, optional)",
-				Required:    false,
-			},
-			{
-				Name:        "offset",
-				Type:        "number",
-				Description: "Number of documents to skip for listDocuments (default: 0, optional)",
-				Required:    false,
-			},
-			{
-				Name:        "limit",
-				Type:        "number",
-				Description: "Maximum number of documents to return for listDocuments (default: 10, optional)",
-				Required:    false,
-			},
-			{
-				Name:        "filters",
-				Type:        "object",
-				Description: "Metadata filters for search/listDocuments - exact match on key-value pairs (optional)",
-				Required:    false,
-			},
-		},
-		Handler: func(agentContext map[string]any, args map[string]any) llms.ToolReturn {
-			action, ok := args["action"].(string)
-			if !ok {
-				return core.NewErrorResponse("action parameter is required and must be a string")
-			}
-
-			switch action {
-			case "index":
-				return v.index(args)
-			case "indexFile":
-				return v.indexFile(args)
-			case "search":
-				return v.search(args)
-			case "listDocuments":
-				return v.listDocuments(args)
-			case "delete":
-				return v.delete(args)
-			default:
-				return core.NewErrorResponse(fmt.Sprintf("unknown action: %s. Valid actions are: index, indexFile, search, listDocuments, delete", action))
-			}
-		},
-	}
-}
diff --git a/src/tools/vector/tool_test.go b/src/tools/vector/tool_test.go
deleted file mode 100644
index 9e58e26..0000000
--- a/src/tools/vector/tool_test.go
+++ /dev/null
@@ -1,135 +0,0 @@
-package vector
-
-import (
-	"errors"
-	"testing"
-
-	"github.com/thinktwiceco/agent-forge/src/core"
-)
-
-// MockVectorDB
-type mockVectorDB struct {
-	storedDocs map[string]core.DocumentSummary
-	indexErr   error
-	searchErr  error
-	deleteErr  error
-}
-
-func (m *mockVectorDB) Index(embedding []float32, text string, metadata map[string]any, model string) (string, error) {
-	if m.indexErr != nil {
-		return "", m.indexErr
-	}
-	id := "doc-123"
-	if m.storedDocs == nil {
-		m.storedDocs = make(map[string]core.DocumentSummary)
-	}
-	m.storedDocs[id] = core.DocumentSummary{
-		DocumentID: id,
-		Text:       text,
-		Metadata:   metadata,
-	}
-	return id, nil
-}
-
-func (m *mockVectorDB) Search(emb []float32, topK int, filters map[string]any) ([]core.SearchResult, error) {
-	if m.searchErr != nil {
-		return nil, m.searchErr
-	}
-	return []core.SearchResult{
-		{DocumentID: "doc-1", Text: "match", Score: 0.9},
-	}, nil
-}
-
-func (m *mockVectorDB) ListDocuments(opts core.ListOptions) ([]core.DocumentSummary, int, error) {
-	return []core.DocumentSummary{
-		{DocumentID: "doc-1", Text: "match"},
-	}, 1, nil
-}
-
-func (m *mockVectorDB) Delete(id string) error {
-	return m.deleteErr
-}
-
-// MockEmbeddingGenerator
-type mockEmbedder struct {
-	err error
-}
-
-func (m *mockEmbedder) GenerateEmbedding(text string) ([]float32, string, error) {
-	if m.err != nil {
-		return nil, "", m.err
-	}
-	return []float32{0.1, 0.2, 0.3}, "mock-model", nil
-}
-func (m *mockEmbedder) ModelName() string { return "mock-embedal" }
-
-func TestVectorTool_Handlers(t *testing.T) {
-	mockDB := &mockVectorDB{}
-	mockEmb := &mockEmbedder{}
-	tool := NewVectorTool(mockDB, mockEmb)
-
-	// 1. Index
-	t.Run("index_success", func(t *testing.T) {
-		args := map[string]any{
-			"action": "index",
-			"text":   "hello world",
-		}
-		result := tool.Call(nil, args)
-		if !result.Success() {
-			t.Errorf("Index failed: %s", result.Error())
-		}
-		if result.Data() != "Document indexed successfully with ID: doc-123" {
-			t.Errorf("Unexpected output: %s", result.Data())
-		}
-	})
-
-	// 2. Search
-	t.Run("search_success", func(t *testing.T) {
-		args := map[string]any{
-			"action": "search",
-			"query":  "hello",
-		}
-		result := tool.Call(nil, args)
-		if !result.Success() {
-			t.Errorf("Search failed: %s", result.Error())
-		}
-	})
-
-	// 3. Delete
-	t.Run("delete_success", func(t *testing.T) {
-		args := map[string]any{
-			"action":      "delete",
-			"document_id": "doc-123",
-		}
-		result := tool.Call(nil, args)
-		if !result.Success() {
-			t.Errorf("Delete failed: %s", result.Error())
-		}
-	})
-
-	// 4. Missing Action
-	t.Run("missing_action", func(t *testing.T) {
-		args := map[string]any{}
-		// Call directly or via Tool.Call validator?
-		// Tool logic validates params before Handler, but Handler also checks.
-		// Since "action" is required in params, validation fails first.
-		result := tool.Call(nil, args)
-		if result.Success() {
-			t.Error("Expected failure for missing action")
-		}
-	})
-
-	// 5. Index Failure (Embedding)
-	t.Run("index_embed_fail", func(t *testing.T) {
-		badEmb := &mockEmbedder{err: errors.New("embed fail")}
-		toolBad := NewVectorTool(mockDB, badEmb)
-		args := map[string]any{
-			"action": "index",
-			"text":   "fail",
-		}
-		result := toolBad.Call(nil, args)
-		if result.Success() {
-			t.Error("Expected index failure due to embedding error")
-		}
-	})
-}
diff --git a/src/tools/vector/types.go b/src/tools/vector/types.go
deleted file mode 100644
index 53b5485..0000000
--- a/src/tools/vector/types.go
+++ /dev/null
@@ -1,9 +0,0 @@
-package vector
-
-import "github.com/thinktwiceco/agent-forge/src/core"
-
-// Vector represents the vector tool instance with its dependencies.
-type Vector struct {
-	vectorDB           core.VectorDB
-	embeddingGenerator core.EmbeddingGenerator
-}
diff --git a/src/tools/vector/validate.go b/src/tools/vector/validate.go
deleted file mode 100644
index 1bce121..0000000
--- a/src/tools/vector/validate.go
+++ /dev/null
@@ -1,24 +0,0 @@
-package vector
-
-import (
-	"fmt"
-)
-
-// validateAction ensures that the action is one of the valid vector tool actions.
-func validateAction(value any) error {
-	action, ok := value.(string)
-	if !ok {
-		return fmt.Errorf("action must be a string")
-	}
-	validActions := map[string]bool{
-		"index":         true,
-		"indexFile":     true,
-		"search":        true,
-		"listDocuments": true,
-		"delete":        true,
-	}
-	if !validActions[action] {
-		return fmt.Errorf("invalid action: %s. Must be one of: index, indexFile, search, listDocuments, delete", action)
-	}
-	return nil
-}
diff --git a/src/tools/web/actNavigate.go b/src/tools/web/actNavigate.go
index f5fe02d..5a7fcb6 100644
--- a/src/tools/web/actNavigate.go
+++ b/src/tools/web/actNavigate.go
@@ -26,8 +26,8 @@ func (w *WebBrowser) navigate(agentContext map[string]any, args map[string]any)
 		return core.NewErrorResponse(fmt.Sprintf("invalid URL: %v", err))
 	}
 
-	// Get or create browser context with headless=false to follow navigation
-	ctx, err := getOrCreateBrowser(agentContext, false)
+	// Get or create browser context using the configured default headless mode.
+	ctx, err := getOrCreateBrowser(agentContext)
 	if err != nil {
 		w.sessionManager.RecordOperation(false)
 		return core.NewErrorResponse(fmt.Sprintf("failed to initialize browser: %v", err))
diff --git a/src/tools/web/actRefresh.go b/src/tools/web/actRefresh.go
index a82ab72..2464140 100644
--- a/src/tools/web/actRefresh.go
+++ b/src/tools/web/actRefresh.go
@@ -12,7 +12,7 @@ import (
 
 // refresh reloads the current browser page.
 func (w *WebBrowser) refresh(agentContext map[string]any) llms.ToolReturn {
-	ctx, err := getOrCreateBrowser(agentContext, false)
+	ctx, err := getOrCreateBrowser(agentContext)
 	if err != nil {
 		w.sessionManager.RecordOperation(false)
 		return core.NewErrorResponse(fmt.Sprintf("failed to initialize browser: %v", err))
diff --git a/src/tools/web/browser.go b/src/tools/web/browser.go
index c5afaab..9646d44 100644
--- a/src/tools/web/browser.go
+++ b/src/tools/web/browser.go
@@ -3,6 +3,9 @@ package web
 import (
 	"context"
 	"fmt"
+	"os"
+	"strconv"
+	"strings"
 
 	"github.com/chromedp/chromedp"
 	agentforge "github.com/thinktwiceco/agent-forge/src"
@@ -13,8 +16,28 @@ import (
 // Global session manager instance
 var globalSessionManager = NewSessionManager()
 
+const webToolHeadlessEnv = "WEB_TOOL_HEADLESS"
+
+// defaultHeadlessMode resolves the default browser mode.
+// Defaults to true and can be overridden via WEB_TOOL_HEADLESS=true|false.
+func defaultHeadlessMode() bool {
+	raw, ok := os.LookupEnv(webToolHeadlessEnv)
+	if !ok || strings.TrimSpace(raw) == "" {
+		return true
+	}
+
+	headless, err := strconv.ParseBool(strings.TrimSpace(raw))
+	if err != nil {
+		agentforge.Info("Invalid %s value %q; defaulting to headless=true", webToolHeadlessEnv, raw)
+		return true
+	}
+
+	return headless
+}
+
 // getOrCreateBrowser gets an existing browser context or creates a new one.
-// headless controls whether the browser runs in headless mode (default: false).
+// headless controls whether the browser runs in headless mode.
+// When omitted, the default is true and can be overridden via WEB_TOOL_HEADLESS.
 // The browser context persists across tool calls.
 func getOrCreateBrowser(agentContext map[string]any, headless ...bool) (context.Context, error) {
 	return globalSessionManager.GetOrCreateBrowser(agentContext, headless...)
@@ -125,7 +148,7 @@ func (w *WebBrowser) listSessions() llms.ToolReturn {
 
 // openSession opens a new named browser session or resumes an existing one.
 func (w *WebBrowser) openSession(agentContext map[string]any, args map[string]any) llms.ToolReturn {
-	headless := false
+	headless := defaultHeadlessMode()
 	if h, ok := args["headless"].(bool); ok {
 		headless = h
 	}
diff --git a/src/tools/web/session_manager.go b/src/tools/web/session_manager.go
index 47868bd..f101108 100644
--- a/src/tools/web/session_manager.go
+++ b/src/tools/web/session_manager.go
@@ -207,7 +207,8 @@ func (sm *SessionManager) getSessionKey(agentContext map[string]any) string {
 }
 
 // GetOrCreateBrowser gets an existing browser context or creates a new one.
-// headless controls whether the browser runs in headless mode (default: false).
+// headless controls whether the browser runs in headless mode.
+// When omitted, the default is true and can be overridden via WEB_TOOL_HEADLESS.
 // The browser context persists across tool calls.
 func (sm *SessionManager) GetOrCreateBrowser(agentContext map[string]any, headless ...bool) (context.Context, error) {
 	sessionKey := sm.getSessionKey(agentContext)
@@ -234,8 +235,8 @@ func (sm *SessionManager) GetOrCreateBrowser(agentContext map[string]any, headle
 		}
 	}
 
-	// Determine headless mode (default to false for better debugging)
-	headlessMode := false
+	// Determine headless mode (default to true, overridable via WEB_TOOL_HEADLESS)
+	headlessMode := defaultHeadlessMode()
 	if len(headless) > 0 {
 		headlessMode = headless[0]
 	}
diff --git a/src/tools/web/tool.go b/src/tools/web/tool.go
index 12b95df..87a888f 100644
--- a/src/tools/web/tool.go
+++ b/src/tools/web/tool.go
@@ -103,7 +103,7 @@ func NewWebTool(dir string) llms.Tool {
 		case "open_session":
 			return `open_session: Open a new named browser session or resume an existing one.
 - Optional: session (string) — name for the session (default: "default"); reuse the same name to resume
-- Optional: headless (boolean, default false) — run browser headlessly
+- Optional: headless (boolean, default: WEB_TOOL_HEADLESS or true) — run browser headlessly
 - Returns confirmation of whether the session was newly created or resumed`
 		default:
 			return fmt.Sprintf("Nothing to add about %s", item)
@@ -112,7 +112,7 @@ func NewWebTool(dir string) llms.Tool {
 
 	return &core.Tool{
 		Name:        "web_browser",
-		Description: "Navigate the web, pull content from pages, interact with buttons and form inputs using a headless browser, and search the web via the Brave Search API.",
+		Description: "Navigate the web, pull content from pages, interact with buttons and form inputs using a browser, and search the web via the Brave Search API.",
 		AdvanceDesc: `Advanced Details:
 - Available actions: open_session, navigate, click, fill, fill_secret, get_content, save_content, web_search, upload_file, refresh, list_sessions, close_session
   Use expand tool with details_about="<action>" for full parameter details on any action.
@@ -125,6 +125,8 @@ func NewWebTool(dir string) llms.Tool {
   * Use web_search to find URLs before navigating
   * Use click/fill to interact with page elements
 - Behavior:
+  * New browser sessions default to headless mode; set WEB_TOOL_HEADLESS=false to make them visible by default
+  * Passing headless explicitly to open_session overrides the environment-based default
   * Browser context (cookies, history) is preserved across calls within the same session
   * web_search calls the Brave Search API directly, no browser needed`,
 		DetailsAboutFunc: detailsAbout,
@@ -158,7 +160,7 @@ func NewWebTool(dir string) llms.Tool {
 			{
 				Name:        "headless",
 				Type:        "boolean",
-				Description: "Whether to run the browser in headless mode (optional for 'open_session', default: false)",
+				Description: "Whether to run the browser in headless mode (optional for 'open_session'; defaults to WEB_TOOL_HEADLESS if set, otherwise true)",
 				Required:    false,
 			},
 			{
diff --git a/src/tools/web/tool_test.go b/src/tools/web/tool_test.go
index e99187e..59f2005 100644
--- a/src/tools/web/tool_test.go
+++ b/src/tools/web/tool_test.go
@@ -87,3 +87,33 @@ func TestNewWebTool(t *testing.T) {
 		t.Error("action param should be required")
 	}
 }
+
+func TestDefaultHeadlessMode(t *testing.T) {
+	t.Run("defaults to true when env unset", func(t *testing.T) {
+		t.Setenv(webToolHeadlessEnv, "")
+		if got := defaultHeadlessMode(); !got {
+			t.Fatalf("defaultHeadlessMode() = %v, want true", got)
+		}
+	})
+
+	t.Run("reads false from env", func(t *testing.T) {
+		t.Setenv(webToolHeadlessEnv, "false")
+		if got := defaultHeadlessMode(); got {
+			t.Fatalf("defaultHeadlessMode() = %v, want false", got)
+		}
+	})
+
+	t.Run("reads true from env", func(t *testing.T) {
+		t.Setenv(webToolHeadlessEnv, "true")
+		if got := defaultHeadlessMode(); !got {
+			t.Fatalf("defaultHeadlessMode() = %v, want true", got)
+		}
+	})
+
+	t.Run("falls back to true on invalid env", func(t *testing.T) {
+		t.Setenv(webToolHeadlessEnv, "not-a-bool")
+		if got := defaultHeadlessMode(); !got {
+			t.Fatalf("defaultHeadlessMode() = %v, want true", got)
+		}
+	})
+}