Merge pull request #84 from VioletCranberry/feat/init-controller-config

feat(init): make the generated cocosearch.yaml a complete config reference

Author: VioletCranberry

README.md

@@ -617,6 +617,10 @@ controller:
   model: qwen2.5:3b     # default depends on provider
   # baseUrl: http://localhost:11434
   # timeout: 5.0        # seconds; on timeout, falls back to the original query
+
+# Optional file logging (default: disabled)
+logging:
+  file: false           # true -> ~/.cocosearch/logs/cocosearch.log (10MB rotation)
 ```
 
 ### Remote Embedding Providers

docs/cli-reference.md

@@ -224,12 +224,14 @@ uv run cocosearch index . --deps
 
 **Initialize project configuration:** `uv run cocosearch init [options]`
 
-Creates a `cocosearch.yaml` starter configuration file in the current directory. After creating the config file, interactively offers to:
+Creates a `cocosearch.yaml` starter configuration file in the current directory. The generated config documents every section as commented examples — `indexing`, `search`, `embedding` (provider/model/baseUrl for ollama/openai/openrouter), the optional query-rewrite `controller`, and file `logging` — so it doubles as a config reference. After creating the config file, interactively offers to:
 1. Add a CocoSearch tool routing table to CLAUDE.md (local project or global `~/.claude/CLAUDE.md`)
 2. Add a CocoSearch tool routing table to AGENTS.md (local project or global `~/.config/opencode/AGENTS.md`)
 3. Register CocoSearch MCP server with OpenCode (local or global `opencode.json`)
 4. Install CocoSearch workflow skills for OpenCode (local or global skills directory)
 5. Install CocoSearch plugin for Claude Code (via `claude` CLI)
+6. Configure Claude Code tool permissions for CocoSearch (local `.claude/settings.local.json` or shared `.claude/settings.json`)
+7. Install the Claude Code nudge hook that steers the agent toward `search_code` instead of raw grep/glob (local or shared settings)
 
 | Flag | Description |
 | ---- | ----------- |
@@ -238,13 +240,15 @@ Creates a `cocosearch.yaml` starter configuration file in the current directory.
 | `--no-opencode-mcp` | Skip the OpenCode MCP server registration prompt |
 | `--no-opencode-skills` | Skip the OpenCode workflow skills installation prompt |
 | `--no-claude-mcp` | Skip the Claude Code plugin installation prompt |
+| `--no-claude-settings` | Skip the Claude Code tool permissions prompt |
+| `--no-claude-hook` | Skip the Claude Code nudge hook prompt |
 
 ```bash
 # Interactive: creates cocosearch.yaml, then prompts for all integrations
 uv run cocosearch init
 
 # Non-interactive: creates cocosearch.yaml only
-uv run cocosearch init --no-claude-md --no-agents-md --no-opencode-mcp --no-opencode-skills --no-claude-mcp
+uv run cocosearch init --no-claude-md --no-agents-md --no-opencode-mcp --no-opencode-skills --no-claude-mcp --no-claude-settings --no-claude-hook
 ```
 
 All interactive prompts are skipped automatically when stdin is not a TTY (e.g., in CI pipelines or when piping input).

src/cocosearch/config/generator.py

@@ -48,8 +48,37 @@
 
 # Embedding settings
 embedding: {}
-  # Ollama model for embeddings
+  # Provider: ollama (default, local), openai, or openrouter
+  # provider: ollama
+  # Model (default depends on provider: ollama -> nomic-embed-text,
+  #   openai -> text-embedding-3-small, openrouter -> openai/text-embedding-3-small)
   # model: nomic-embed-text
+  # Custom / OpenAI-compatible endpoint (Infinity, TEI, vLLM). For the ollama
+  # provider this overrides COCOSEARCH_OLLAMA_URL.
+  # baseUrl: http://localhost:8080
+  # Override the embedding vector size (only if your model needs it)
+  # outputDimension: 768
+  # NOTE: remote providers also need COCOSEARCH_EMBEDDING_API_KEY (env var),
+  # unless baseUrl points at a local server. Switching provider/model requires
+  # a `cocosearch index . --fresh` reindex.
+
+# Optional query-rewrite controller (default: disabled)
+# An LLM expands vague natural-language queries into better search terms before
+# retrieval (e.g. "how does login work" -> "authentication session credential
+# login user token"). When disabled, search is byte-for-byte identical and no
+# generative model is ever called. Configured just like the embedding provider.
+# controller:
+#   enabled: false
+#   provider: ollama        # ollama (default), openai, openrouter
+#   model: qwen2.5:3b       # default depends on provider
+#   # baseUrl: http://localhost:11434   # custom / OpenAI-compatible endpoint
+#   # timeout: 5.0          # seconds; falls back to the original query on timeout
+
+# Logging (default: file output disabled)
+# When enabled, logs are written to ~/.cocosearch/logs/cocosearch.log
+# (10MB rotation, 3 backups). Equivalent to COCOSEARCH_LOG_FILE=true.
+# logging:
+#   file: false
 """
 
 

tests/unit/config/test_generator.py

@@ -13,6 +13,7 @@
     COCOSEARCH_MCP_TOOL_PERMISSIONS,
     COCOSEARCH_NUDGE_MARKER,
     CONFIG_TEMPLATE,
+    CocoSearchConfig,
     ConfigError,
     check_claude_plugin_installed,
     generate_agents_md_routing,
@@ -67,6 +68,59 @@ def test_config_template_contains_linked_indexes_comment():
     assert "common-utils" in CONFIG_TEMPLATE
 
 
+def _uncomment_block(marker: str) -> dict:
+    """Uncomment one '# ' level of the CONFIG_TEMPLATE block beginning at `marker`
+    (a fully-commented section like '# controller:') up to its trailing blank
+    line, then parse it as YAML. Double-commented sub-fields stay commented."""
+    lines = CONFIG_TEMPLATE.splitlines()
+    start = next(i for i, ln in enumerate(lines) if ln.strip() == marker)
+    block = []
+    for ln in lines[start:]:
+        if not ln.startswith("#"):  # blank line ends the block
+            break
+        block.append(ln[2:] if ln.startswith("# ") else ln)
+    return yaml.safe_load("\n".join(block))
+
+
+def test_config_template_contains_controller_comment():
+    """Test that CONFIG_TEMPLATE documents the optional query-rewrite controller."""
+    assert "# controller:" in CONFIG_TEMPLATE
+    assert "enabled: false" in CONFIG_TEMPLATE
+    assert "provider: ollama" in CONFIG_TEMPLATE
+    assert "qwen2.5:3b" in CONFIG_TEMPLATE
+
+
+def test_config_template_controller_example_is_schema_valid():
+    """The commented controller example must validate against ControllerSection
+    once uncommented — guards the docs from drifting out of sync with the schema."""
+    config = CocoSearchConfig(**_uncomment_block("# controller:"))
+    assert config.controller.enabled is False
+    assert config.controller.provider == "ollama"
+    assert config.controller.model == "qwen2.5:3b"
+
+
+def test_config_template_documents_embedding_provider():
+    """Test that CONFIG_TEMPLATE documents the multi-provider embedding options."""
+    assert "provider: ollama" in CONFIG_TEMPLATE
+    assert "baseUrl" in CONFIG_TEMPLATE
+    assert "openrouter" in CONFIG_TEMPLATE
+    assert "COCOSEARCH_EMBEDDING_API_KEY" in CONFIG_TEMPLATE
+
+
+def test_config_template_contains_logging_comment():
+    """Test that CONFIG_TEMPLATE documents the optional file logging toggle."""
+    assert "# logging:" in CONFIG_TEMPLATE
+    assert "file: false" in CONFIG_TEMPLATE
+    assert "COCOSEARCH_LOG_FILE" in CONFIG_TEMPLATE
+
+
+def test_config_template_logging_example_is_schema_valid():
+    """The commented logging example must validate against LoggingSection once
+    uncommented — guards the docs from drifting out of sync with the schema."""
+    config = CocoSearchConfig(**_uncomment_block("# logging:"))
+    assert config.logging.file is False
+
+
 class TestClaudeMdRouting:
     """Tests for generate_claude_md_routing."""