refactor(config)!: make config sections orthogonal (#731) (#747)

Rearchitect the config system so each section is self-contained with no
cross-section value inheritance. Kill the shared [llm] base section and
replace it with independent [chat.llm] and [extraction.llm] sections.
Move OCR TSV settings into their own [extraction.ocr.tsv] sub-section.

- Remove all deprecated key migration code, env var renames, and
  backward-compatibility shims
- Remove deprecated MICASA_CURRENCY env var; only MICASA_LOCALE_CURRENCY
  is supported
- Remove redundant llmExtraContext field; use chatCfg.ExtraContext
- Remove dead collectValues/allValues code from ShowConfig
- Combine env source and deprecation comments in config --dump output
- Rename persisted settings DB key from llm.model to chat.llm.model
- Update all docs, VHS tapes, error messages, and codebase maps
- Add AGENTS.md rules for resisting configuration and orthogonality

BREAKING CHANGE: The [llm] config section and all deprecated env vars
(MICASA_LLM_*, MICASA_EXTRACTION_MODEL, MICASA_EXTRACTION_TIMEOUT,
MICASA_CURRENCY) have been removed. Use [chat.llm] and [extraction.llm]
sections with their corresponding MICASA_CHAT_LLM_* and
MICASA_EXTRACTION_LLM_* env vars instead. The persisted model DB key
changed from llm.model to chat.llm.model; existing model preferences
will reset on first use.

Closes #731

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: cpcloud

.claude/codebase/types.md

@@ -121,16 +121,19 @@ Col* (e.g., ColID = "id", ColName = "name", ColDeletedAt = "deleted_at")
 ## Config Types (internal/config/)
 
 ### Config (config.go)
-- LLM (provider, model, baseURL, apiKey, timeout, thinking, extraContext)
-  - Chat/Extraction overrides (LLMChatOverride, LLMExtractionOverride)
+- Chat (Enable *bool, LLM ChatLLM)
+  - ChatLLM (Provider, BaseURL, Model, APIKey, Timeout, Thinking, ExtraContext)
+- Extraction (MaxPages int, LLM ExtractionLLM, OCR)
+  - ExtractionLLM (Enable *bool, Provider, BaseURL, Model, APIKey, Timeout, Thinking)
+  - OCR (Enable *bool, TSV OCRTSV)
+    - OCRTSV (Enable *bool, ConfidenceThreshold *int)
 - Documents (MaxFileSize ByteSize, CacheTTL Duration)
-- Extraction (MaxPages int, Enable *bool, LLMTimeout)
-  - OCR (Enable *bool, ConfidenceThreshold int)
 - Locale (Currency string)
+Each pipeline section is self-contained; no cross-section inheritance.
 
 ### Defaults
 - Provider: "ollama", Model: "qwen3", BaseURL: "http://localhost:11434"
-- MaxPages: 20, CacheTTL: 30 days, LLMTimeout: 5m
+- MaxPages: 0, CacheTTL: 30 days, LLMTimeout: 5m, OCR TSV threshold: 70
 
 ## LLM Types (internal/llm/)
 

.claude/commands/rev.md

@@ -5,8 +5,9 @@ Rebase onto the latest main, address PR review feedback, and fix failing CI.
 
 ## 1. Rebase onto main
 
-1. `git pull --rebase origin main`
-2. If there are conflicts, resolve them, `git add` the resolved files, and
+1. `git fetch origin main`
+2. `git rebase origin/main`
+3. If there are conflicts, resolve them, `git add` the resolved files, and
    `git rebase --continue`. Repeat until the rebase completes.
 
 ## 2. Address PR review feedback and fix CI (parallel)

AGENTS.md

@@ -210,8 +210,6 @@ details; do not duplicate that detail here.
 
 ### Git and CI
 
-- **Rebase with one command**: Use `git pull --rebase origin main` instead
-  of separate `git fetch origin main` + `git rebase origin/main`.
 - **Reply to PR review comments**: After addressing a PR review comment,
   reply to the comment on GitHub (via `gh api .../replies`) explaining
   how it was addressed (commit hash, what changed, tests added). Do this
@@ -269,6 +267,19 @@ details; do not duplicate that detail here.
   complete backup. Never store app state outside SQLite.
 - **LLM is opt-in, not a crutch**: Every feature must work fully without
   the LLM. The LLM enhances; it does not substitute.
+- **Resist configuration**: Push back when the user asks to make something
+  configurable. Most things should not be. Prefer sensible defaults,
+  auto-detection, and convention over configuration. Every config knob is
+  a maintenance burden, a documentation obligation, and a combinatorial
+  testing surface. Only add configuration when there is a concrete,
+  demonstrated need -- not a hypothetical one.
+- **Orthogonal configuration**: When configuration is warranted and agreed
+  upon, each config value must interact predictably -- or preferably not
+  at all -- with every other config value. No value in one section should
+  silently affect values in another section. No inheritance chains, no
+  cascading defaults across sections, no "this overrides that unless the
+  other thing is set." If two pipelines need the same setting, they each
+  get their own independent copy.
 - **Deterministic ordering requires tiebreakers**: Every `ORDER BY` that
   could tie MUST include a tiebreaker (typically `id DESC`).
 - **Audit new deps before adding**: Review source for security issues

cmd/micasa/main.go

@@ -43,7 +43,7 @@ type backupCmd struct {
 }
 
 type configCmd struct {
-	Key  string `arg:"" optional:"" help:"Dot-delimited config key (e.g. llm.model, documents.max_file_size)."`
+	Key  string `arg:"" optional:"" help:"Dot-delimited config key (e.g. chat.llm.model, documents.max_file_size)."`
 	Dump bool   `                   help:"Print the fully resolved config as TOML and exit."`
 }
 
@@ -147,34 +147,35 @@ func (cmd *runCmd) Run() error {
 		FilePickerDir: cfg.Documents.ResolvedFilePickerDir(),
 	}
 
-	chatCfg := cfg.LLM.ChatConfig()
-	opts.SetLLM(
-		chatCfg.Provider,
-		chatCfg.BaseURL,
-		chatCfg.Model,
-		chatCfg.APIKey,
-		chatCfg.ExtraContext,
-		chatCfg.Timeout,
-		chatCfg.Thinking,
+	chatLLM := cfg.Chat.LLM
+	opts.SetChat(
+		cfg.Chat.IsEnabled(),
+		chatLLM.Provider,
+		chatLLM.BaseURL,
+		chatLLM.Model,
+		chatLLM.APIKey,
+		chatLLM.ExtraContext,
+		chatLLM.TimeoutDuration(),
+		chatLLM.Thinking,
 	)
 
-	exCfg := cfg.LLM.ExtractionConfig()
+	exLLM := cfg.Extraction.LLM
 	extractors := extract.DefaultExtractors(
 		cfg.Extraction.MaxPages,
 		0, // pdftotext uses its own internal default timeout (30s)
-		cfg.Extraction.IsOCREnabled(),
+		cfg.Extraction.OCR.IsEnabled(),
 	)
 	opts.SetExtraction(
-		exCfg.Provider,
-		exCfg.BaseURL,
-		exCfg.Model,
-		exCfg.APIKey,
-		exCfg.Timeout,
-		exCfg.Thinking,
+		exLLM.Provider,
+		exLLM.BaseURL,
+		exLLM.Model,
+		exLLM.APIKey,
+		exLLM.TimeoutDuration(),
+		exLLM.Thinking,
 		extractors,
-		cfg.Extraction.IsEnabled(),
-		cfg.Extraction.IsOCRTSV(),
-		cfg.Extraction.OCRConfThreshold(),
+		exLLM.IsEnabled(),
+		cfg.Extraction.OCR.TSV.IsEnabled(),
+		cfg.Extraction.OCR.TSV.Threshold(),
 	)
 
 	model, err := app.NewModel(store, opts)

cmd/micasa/main_test.go

@@ -152,10 +152,10 @@ func TestConfigCmd(t *testing.T) {
 			t.Context(),
 			bin,
 			"config",
-			"llm.model",
+			"chat.llm.model",
 		)
 		out, err := cmd.CombinedOutput()
-		require.NoError(t, err, "config llm.model failed: %s", out)
+		require.NoError(t, err, "config chat.llm.model failed: %s", out)
 		got := strings.TrimSpace(string(out))
 		assert.NotEmpty(t, got)
 	})

docs/content/blog/llm-plumbing.md

@@ -39,10 +39,10 @@ over at Mozilla.
 
 Back to the tech.
 
-The provider details are configured in your [micasa config](/docs/reference/configuration/#llm-section):
+The provider details are configured in your [micasa config](/docs/reference/configuration/#chatllm-section):
 
 ```toml
-[llm]
+[chat.llm]
 provider = "anthropic"
 model = "claude-sonnet-4-5-latest"
 api_key = "sk-..."
@@ -63,19 +63,19 @@ They used to share a model. Now they don't
 ([#575](https://github.com/cpcloud/micasa/pull/575)):
 
 ```toml
-[llm]
+[chat.llm]
 provider = "ollama"
 model = "qwen3"
 
-[llm.extraction]
+[extraction.llm]
 provider = "anthropic"
 model = "claude-haiku-4-5-latest"
 api_key = "sk-..."
 ```
 
 Chat runs locally, extraction runs on Anthropic. Or both local. Or both cloud.
-`[llm]` is the default; `[llm.chat]` and `[llm.extraction]` override whatever
-you want per-pipeline.
+Each pipeline has its own independent `[chat.llm]` and `[extraction.llm]`
+sections -- no inheritance, no cross-contamination.
 
 ## Picking models at runtime
 
@@ -102,7 +102,7 @@ look before it writes.
 - **[Locale-aware currency](/docs/reference/configuration/#locale-section)** --
   EUR gets comma decimals and period grouping (`1.234,56`), GBP gets the pound
   sign, JPY drops decimal places. Auto-detected from your system locale or set
-  via `MICASA_CURRENCY`.
+  via `MICASA_LOCALE_CURRENCY`.
   ([#467](https://github.com/cpcloud/micasa/pull/467))
 - **[Imperial/metric toggle](/docs/guide/house-profile/)** -- <kbd>U</kbd> switches
   between square feet and square meters. Defaults to metric unless your locale
@@ -136,9 +136,9 @@ go run github.com/cpcloud/micasa/cmd/micasa@latest --demo
 Or with a cloud provider:
 
 ```sh
-export MICASA_LLM_PROVIDER=anthropic
-export MICASA_LLM_MODEL=claude-haiku-4-5-latest
-export MICASA_LLM_API_KEY=sk-...
+export MICASA_CHAT_LLM_PROVIDER=anthropic
+export MICASA_CHAT_LLM_MODEL=claude-haiku-4-5-latest
+export MICASA_CHAT_LLM_API_KEY=sk-...
 go run github.com/cpcloud/micasa/cmd/micasa@latest --demo
 ```
 

docs/content/docs/guide/llm-chat.md

@@ -211,12 +211,12 @@ micasa connects over plain HTTP by default. Consider:
 - **Network exposure** -- anyone who can intercept traffic between you and a
   remote HTTP endpoint can read your home data
 
-The LLM feature is entirely optional. If you never configure an `[llm]`
+The LLM feature is entirely optional. If you never configure a `[chat.llm]`
 section, no data is ever sent anywhere.
 
 ## Configuration
 
-The chat requires an `[llm]` section in your config file. If no LLM is
+The chat requires a `[chat.llm]` section in your config file. If no LLM is
 configured, the chat overlay shows a helpful hint with the config path and
 a sample configuration.