Warn on unknown config keys, skip welcome notes in existing vaults

- Unknown TOML keys now print warnings with suggestions
  (e.g. "exclude_paths" → did you mean "skip_dirs"?)
- Welcome notes skipped if vault already has markdown files
- Fixes silent config failures that caused skip_dirs to not work

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

Author: sgx-labs

CHANGELOG.md

@@ -13,6 +13,8 @@
 
 ### Fixed
 
+- **Unknown config keys now warn** — unrecognized keys in `config.toml` print a warning with suggestions (e.g. `exclude_paths` → `skip_dirs`). Previously unknown keys were silently ignored.
+- **Welcome notes skip existing vaults** — `same init` no longer creates `welcome/` in vaults that already have markdown files. Governed vaults with existing structure are left untouched.
 - **`SAME_EMBED_BASE_URL` missing from `LoadConfig()`** — the env var was handled in `EmbeddingProviderConfig()` but not in the config-file loader, causing inconsistency when both paths were used.
 - **`OPENAI_API_KEY` fallback for `openai-compatible`** — `LoadConfig()` now checks the env var for both `openai` and `openai-compatible` providers.
 - **`BaseURL` not passed to embedding provider** — `indexer.go` and `init.go` now pass the configured `BaseURL` when constructing embedding providers, fixing silent failures when using `openai-compatible` with a custom endpoint.

internal/config/config.go

@@ -187,9 +187,11 @@ func LoadConfig() (*Config, error) {
 	// Try to load TOML config file
 	configPath := findConfigFile()
 	if configPath != "" {
-		if _, err := toml.DecodeFile(configPath, cfg); err != nil {
+		meta, err := toml.DecodeFile(configPath, cfg)
+		if err != nil {
 			return nil, fmt.Errorf("parse config %s: %w", configPath, err)
 		}
+		warnUnknownKeys(meta, configPath)
 	}
 
 	// Environment variables override TOML values
@@ -259,9 +261,11 @@ func LoadConfigFrom(configPath string) (*Config, error) {
 
 	if configPath != "" {
 		if _, err := os.Stat(configPath); err == nil {
-			if _, err := toml.DecodeFile(configPath, cfg); err != nil {
+			meta, err := toml.DecodeFile(configPath, cfg)
+			if err != nil {
 				return nil, fmt.Errorf("parse config %s: %w", configPath, err)
 			}
+			warnUnknownKeys(meta, configPath)
 		}
 	}
 
@@ -563,6 +567,45 @@ func FindConfigFile() string {
 	return findConfigFile()
 }
 
+// configSuggestions maps common wrong keys to the correct TOML key name.
+var configSuggestions = map[string]string{
+	"exclude_paths": "skip_dirs",
+	"exclude_dirs":  "skip_dirs",
+	"skip_paths":    "skip_dirs",
+	"ignored_dirs":  "skip_dirs",
+	"ignore_dirs":   "skip_dirs",
+	"excludes":      "skip_dirs",
+	"noise":         "noise_paths",
+	"apikey":        "api_key",
+	"api-key":       "api_key",
+	"baseurl":       "base_url",
+	"base-url":      "base_url",
+	"token_budget":  "max_token_budget",
+	"budget":        "max_token_budget",
+}
+
+// warnUnknownKeys prints warnings for unrecognized config keys.
+func warnUnknownKeys(meta toml.MetaData, configPath string) {
+	undecoded := meta.Undecoded()
+	if len(undecoded) == 0 {
+		return
+	}
+
+	fname := filepath.Base(configPath)
+	for _, key := range undecoded {
+		keyStr := key.String()
+		lastPart := key[len(key)-1]
+
+		if suggestion, ok := configSuggestions[lastPart]; ok {
+			fmt.Fprintf(os.Stderr, "same: WARNING: unknown key %q in %s — did you mean %q?\n",
+				keyStr, fname, suggestion)
+		} else {
+			fmt.Fprintf(os.Stderr, "same: WARNING: unknown key %q in %s (will be ignored)\n",
+				keyStr, fname)
+		}
+	}
+}
+
 // defaultSkipDirs are directories to skip during vault walks.
 // SECURITY: _PRIVATE contains client-sensitive content and must never be indexed
 // or auto-surfaced. Access to _PRIVATE requires explicit MCP tool calls.

internal/config/config_security_test.go

@@ -176,6 +176,54 @@ func TestLoadConfig_AllEnvVars(t *testing.T) {
 	}
 }
 
+func TestLoadConfig_UnknownKeys(t *testing.T) {
+	dir := t.TempDir()
+	configDir := filepath.Join(dir, ".same")
+	os.MkdirAll(configDir, 0o755)
+
+	// Config with unknown keys — should not error but should warn
+	os.WriteFile(filepath.Join(configDir, "config.toml"),
+		[]byte(`[vault]
+exclude_paths = ["_Raw", "Scratch"]
+path = "/home/user/notes"
+
+[embedding]
+provider = "ollama"
+`), 0o644)
+
+	t.Setenv("VAULT_PATH", dir)
+	VaultOverride = dir
+	defer func() { VaultOverride = "" }()
+
+	cfg, err := LoadConfig()
+	if err != nil {
+		t.Fatalf("unknown keys should not cause error: %v", err)
+	}
+	// Valid keys should still be parsed (VAULT_PATH env overrides toml path, so check provider)
+	if cfg.Embedding.Provider != "ollama" {
+		t.Errorf("expected embedding provider to be parsed, got %q", cfg.Embedding.Provider)
+	}
+}
+
+func TestConfigSuggestions(t *testing.T) {
+	// Verify the suggestions map has expected entries
+	tests := []struct {
+		wrong   string
+		correct string
+	}{
+		{"exclude_paths", "skip_dirs"},
+		{"exclude_dirs", "skip_dirs"},
+		{"skip_paths", "skip_dirs"},
+		{"apikey", "api_key"},
+		{"base-url", "base_url"},
+	}
+	for _, tt := range tests {
+		if got, ok := configSuggestions[tt.wrong]; !ok || got != tt.correct {
+			t.Errorf("configSuggestions[%q] = %q, want %q", tt.wrong, got, tt.correct)
+		}
+	}
+}
+
 func TestLoadConfig_NoEnvVars(t *testing.T) {
 	// Unset all SAME-related env vars
 	t.Setenv("VAULT_PATH", "")

internal/setup/init.go

@@ -579,6 +579,12 @@ func copyWelcomeNotes(vaultPath string) {
 		return
 	}
 
+	// Skip welcome notes if the vault already has markdown content.
+	// Governed vaults (with CLAUDE.md, README.md, etc.) don't need starter notes.
+	if vaultHasNotes(vaultPath) {
+		return
+	}
+
 	// Create the directory
 	if err := os.MkdirAll(destDir, 0o755); err != nil {
 		// Silently skip if we can't create the directory
@@ -617,6 +623,21 @@ func copyWelcomeNotes(vaultPath string) {
 	}
 }
 
+// vaultHasNotes checks if the vault root already contains markdown files.
+// Used to skip welcome note generation for vaults with existing content.
+func vaultHasNotes(vaultPath string) bool {
+	entries, err := os.ReadDir(vaultPath)
+	if err != nil {
+		return false
+	}
+	for _, e := range entries {
+		if !e.IsDir() && strings.HasSuffix(e.Name(), ".md") {
+			return true
+		}
+	}
+	return false
+}
+
 // detectVault finds or prompts for the vault path.
 func detectVault(autoAccept bool) (string, error) {
 	cwd, err := os.Getwd()