Use one model config setting and document config-first setup

Author: ktappdev

README.md

@@ -26,6 +26,10 @@ ctxt status
 
 The first run creates `.ctxt/ctx_config.toml` and starts indexing right away. You can edit the config later; CLI flags override config values. Start `ctxt watch .` when you want a live index that follows file changes.
 
+**Want to choose a model before indexing?** Run `ctxt config init` first,
+edit `model` under `[llm]` in `.ctxt/ctx_config.toml`, then run `ctxt init .`.
+See [config setup](#ctxt-config-init) for details.
+
 LLM synonyms are optional. To enable them, set `OPENROUTER_API_KEY` in your shell or secret manager before running `ctxt init .`. Without a key, indexing still works with lexical matching.
 
 ## LLM flexibility
@@ -254,10 +258,27 @@ ctxt doctor --json
 
 ### `ctxt config init`
 
-Create or overwrite `.ctxt/ctx_config.toml`:
+Create `.ctxt/ctx_config.toml` before indexing if you want to choose your model
+or customize ignore rules first:
+
+```bash
+ctxt config init
+```
+
+Edit `model` under `[llm]` in the generated file, then build the index:
+
+```bash
+ctxt init .
+```
+
+`--output` selects a different config path. Existing files are preserved;
+`--force` explicitly overwrites them with the starter defaults.
+
+After indexing, changing the model does not invalidate cached synonyms. To
+regenerate synonyms with your saved model, run:
 
 ```bash
-ctxt config init --output .ctxt/ctx_config.toml
+ctxt sync . --force
 ```
 
 ## Configuration
@@ -268,7 +289,6 @@ ctxt config init --output .ctxt/ctx_config.toml
 [common]
 output = ".ctxt/ctx_index.json"
 synonym_cache = ".ctxt/ctx_cache.json"
-llm_model = "deepseek/deepseek-v4-flash"
 batch_size = 8               # names per LLM request; 0 enables smart batching
 synonyms_min = 5             # min synonyms per name
 synonyms_max = 12            # max synonyms per name
@@ -287,6 +307,9 @@ parallel_requests = 10       # concurrent LLM batches
 
 **LLM config resolution:** flag → config `api_key` → config `api_key_env` → `LLM_API_KEY` → `OPENROUTER_API_KEY`.
 
+**Model selection:** `--llm-model` → `[llm].model` → built-in default. Set the
+saved model only under `[llm]`; `[common].llm_model` is not supported.
+
 **Supported providers:** OpenRouter (default) and APIs that implement the
 OpenAI chat-completions request/response shape. The `provider` value labels
 the configuration; `endpoint` and `model` control the request.

command_config.go

@@ -18,6 +18,12 @@ func newConfigInitCommand() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "init",
 		Short: "Create starter .ctxt/ctx_config.toml",
+		Long: `Create the project config before indexing so you can choose your model and settings.
+
+From the project root, run "ctxt config init", edit [llm].model in
+.ctxt/ctx_config.toml, then run "ctxt init ." to build the index.
+
+Existing config files are preserved unless you pass --force.`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			target := outPath
 			if target == "" {
@@ -27,6 +33,7 @@ func newConfigInitCommand() *cobra.Command {
 				return err
 			}
 			LogInfof("Created starter config at %s", target)
+			LogInfof("Edit [llm].model and other settings before indexing your project.")
 			return nil
 		},
 	}

command_examples.go

@@ -13,8 +13,9 @@ func newExamplesCommand() *cobra.Command {
 		Long:  ``,
 		Run: func(cmd *cobra.Command, args []string) {
 			fmt.Print(`Setup:
+  ctxt config init                         Create config to customize before indexing
   ctxt init .                              Build index for current project
-  ctxt init . --model openai/gpt-4o        Use specific model for synonyms
+  ctxt init . --llm-model openai/gpt-4o      Use specific model for synonyms
 
 Search:
   ctxt search-hints "auth"                 Find auth-related files
@@ -37,7 +38,7 @@ Benchmarks:
 Inspection:
   ctxt status                    Show index stats
   ctxt doctor                    Health check
-  ctxt config show               View current config
+  ctxt config --help             See config setup options
   ctxt clean                     Remove all ctxt files
 `)
 		},

command_init.go

@@ -21,9 +21,12 @@ Creates two files:
 
 With an LLM API key, ctxt sends filenames + extracted imports to the LLM to generate domain-accurate synonyms. Without one, falls back to lexical splitting (pascalCase → "pascal case", snake_case → "snake case").
 
+To choose your model before indexing, run "ctxt config init", edit [llm].model
+in .ctxt/ctx_config.toml, then run "ctxt init .".
+
 Examples:
   ctxt init .                                    Basic setup
-  ctxt init . --model openai/gpt-4o              Use specific LLM model
+  ctxt init . --llm-model openai/gpt-4o          Use specific LLM model
   ctxt init . --symbol-extractor treesitter      Force tree-sitter (no regex fallback)
   ctxt init . --symbol-extractor regex           Regex-only extraction
   ctxt init . --synonyms 8                       Generate up to 8 synonyms per name

config.go

@@ -21,7 +21,6 @@ type ContextingConfig struct {
 type CommonConfig struct {
 	OutputPath      string   `toml:"output"`
 	SynonymCache    string   `toml:"synonym_cache"`
-	Model           string   `toml:"llm_model"`
 	APIKey          string   `toml:"api_key"`
 	BatchSize       int      `toml:"batch_size"`
 	SynonymsPerName int      `toml:"synonyms"`

config_apply.go

@@ -5,7 +5,6 @@ import "github.com/spf13/cobra"
 func applyCommonConfig(cmd *cobra.Command, flags *CommonFlags, cfg CommonConfig) {
 	applyStringFlag(cmd, "output", &flags.OutputPath, cfg.OutputPath)
 	applyStringFlag(cmd, "synonym-cache", &flags.SynonymCache, cfg.SynonymCache)
-	applyStringFlag(cmd, "llm-model", &flags.Model, cfg.Model)
 	applyStringFlag(cmd, "api-key", &flags.APIKey, cfg.APIKey)
 	applyIntFlag(cmd, "batch-size", &flags.BatchSize, cfg.BatchSize)
 	applyIntFlag(cmd, "synonyms", &flags.SynonymsPerName, cfg.SynonymsPerName)

config_template.go

@@ -3,7 +3,6 @@ package contexting
 const starterConfigTemplate = `[common]
 output = ".ctxt/ctx_index.json"
 synonym_cache = ".ctxt/ctx_cache.json"
-llm_model = "deepseek/deepseek-v4-flash"
 batch_size = 8               # names per batch; smaller = faster individual requests
 synonyms_min = 5            # min synonyms per name
 synonyms_max = 12           # max synonyms per name
@@ -22,10 +21,6 @@ model = "deepseek/deepseek-v4-flash"
 # api_key = "sk-..."                    # or use api_key_env for security
 api_key_env = "OPENROUTER_API_KEY"      # read key from env var
 # max_tokens = 512
-# provider = "openrouter"
-# endpoint = "https://openrouter.ai/api/v1/chat/completions"
-# model = "deepseek/deepseek-v4-flash"
-# api_key_env = "OPENROUTER_API_KEY"
 
 [init]
 root = "."

config_test.go

@@ -14,11 +14,13 @@ func TestLoadContextingConfig(t *testing.T) {
 	content := `
 [common]
 output = "out/context.json"
-llm_model = "openai/gpt-oss-safeguard-20b"
 batch_size = 12
 ignore = ["dist", "build"]
 verbose = true
 
+[llm]
+model = "openai/gpt-oss-safeguard-20b"
+
 [watch]
 debounce = "2s"
 search_log = false
@@ -47,6 +49,9 @@ show_tokens = true
 	if cfg.Common.BatchSize != 12 {
 		t.Fatalf("unexpected batch size: %d", cfg.Common.BatchSize)
 	}
+	if cfg.LLM.Model != "openai/gpt-oss-safeguard-20b" {
+		t.Fatalf("unexpected LLM model: %s", cfg.LLM.Model)
+	}
 	if cfg.Watch.Debounce != "2s" {
 		t.Fatalf("unexpected debounce: %s", cfg.Watch.Debounce)
 	}

context.toml.example

@@ -1,7 +1,6 @@
 [common]
 output = ".ctxt/ctx_index.json"
 synonym_cache = ".ctxt/ctx_cache.json"
-llm_model = "deepseek/deepseek-v4-flash"
 batch_size = 8              # names per batch; 0 enables smart batching
 synonyms_min = 5            # min synonyms per name
 synonyms_max = 12           # max synonyms per name

docs/DEVELOPER_MANUAL.html

@@ -675,7 +675,6 @@ <h3 id="config-file">ctx_config.toml</h3>
 [common]
 output = ".ctxt/ctx_index.json"              <span class="cmt"># Index output path</span>
 synonym_cache = ".ctx/ctx_cache.json"
-llm_model = "deepseek/deepseek-v4-flash"    <span class="cmt"># Default LLM model (overridden by [llm])</span>
 batch_size = 8                              <span class="cmt"># 0 = smart batching</span>
 synonyms = 10                               <span class="cmt"># Desired synonyms per name</span>
 ignore = [".git", "node_modules", ...]      <span class="cmt"># Extra ignore patterns</span>