mdcontext 0.0.1 → 0.1.0

package/research/config-analysis/04-consolidated-task-candidates.md

@@ -0,0 +1,277 @@
+# Consolidated Configuration Tasks for mdcontext
+
+**Context**: mdcontext already uses `@effect/cli`. This means the Effect ecosystem has lower adoption friction, and Effect Config + Layers is the recommended approach (not c12/citty/Zod).
+
+**Strategy**: Full Effect-native configuration using `Config`, `ConfigProvider`, and `Layer` patterns.
+
+---
+
+## Phase 1: Effect Config Foundation
+
+### Task 1: Create Effect Config Schema Module
+
+**Priority**: High
+**Effort**: Small (2-4 hours)
+**Dependencies**: None
+
+**Description**: Define all configuration options using Effect's `Config` combinators (`Config.string`, `Config.number`, `Config.literal`, etc.). This replaces the Zod schema approach and provides native integration with Effect's ConfigProvider system.
+
+**Why it matters**: Effect Config provides compile-time tracking of config requirements through the type system, eliminating runtime-only validation errors and enabling cleaner dependency injection.
+
+---
+
+### Task 2: Create ConfigService Layer
+
+**Priority**: High
+**Effort**: Small (2-4 hours)
+**Dependencies**: Task 1
+
+**Description**: Wrap configuration in an Effect `Context.Tag` and `Layer`, enabling dependency injection throughout the application. Services will access config via `yield* ConfigService` rather than direct function parameters.
+
+**Why it matters**: Layer-based config enables test isolation without mocking, follows Effect best practices, and provides consistent config access across all commands and services.
+
+---
+
+### Task 3: Implement File-based ConfigProvider
+
+**Priority**: High
+**Effort**: Medium (1-2 days)
+**Dependencies**: Task 1
+
+**Description**: Create a custom `ConfigProvider` that reads from `mdcontext.config.ts` (or `.json`/`.yaml`). Use `ConfigProvider.fromMap` or `ConfigProvider.nested` to map file contents to the Effect config namespace.
+
+**Why it matters**: Enables persistent configuration without repeating CLI flags. Users expect config file support in modern CLI tools.
+
+---
+
+### Task 4: Implement Config Precedence Chain
+
+**Priority**: High
+**Effort**: Medium (4-8 hours)
+**Dependencies**: Task 3
+
+**Description**: Compose ConfigProviders using `ConfigProvider.orElse` to establish precedence: CLI flags > Environment variables > Config file > Defaults. Effect's ConfigProvider composition makes this elegant.
+
+**Why it matters**: Standard CLI behavior. Users expect CLI flags to override everything, env vars to override files, and sensible defaults when nothing is specified.
+
+---
+
+## Phase 2: CLI Integration
+
+### Task 5: Integrate Config Layer with CLI Commands
+
+**Priority**: High
+**Effort**: Medium (1-2 days)
+**Dependencies**: Task 2, Task 4
+
+**Description**: Modify all CLI command handlers to `yield* ConfigService` instead of using inline defaults. Update `@effect/cli` Options to use `Config` values as defaults where appropriate. Each command should `.pipe(Effect.provide(ConfigLive))`.
+
+**Why it matters**: Completes the config system integration. Users can now set persistent defaults in config files that CLI commands respect.
+
+---
+
+### Task 6: Add Global --config Flag
+
+**Priority**: Medium
+**Effort**: Small (2-4 hours)
+**Dependencies**: Task 5
+
+**Description**: Add `Options.file("config").pipe(Options.withAlias("c"))` as a global option that overrides the config file search path. Pass this to the ConfigProvider construction.
+
+**Why it matters**: Allows per-invocation config file selection, useful for testing and multi-project setups.
+
+---
+
+### Task 7: Add config init Subcommand
+
+**Priority**: Low
+**Effort**: Small (2-4 hours)
+**Dependencies**: Task 3
+
+**Description**: Create `mdcontext config init` command that generates a starter `mdcontext.config.ts` with `defineConfig()` helper and documented defaults.
+
+**Why it matters**: Lowers barrier to config adoption and documents available options by example.
+
+---
+
+## Phase 3: Environment & Secrets
+
+### Task 8: Implement MDCONTEXT\_ Environment Variable Mapping
+
+**Priority**: Medium
+**Effort**: Small (2-4 hours)
+**Dependencies**: Task 1
+
+**Description**: Configure Effect's default `ConfigProvider.fromEnv()` with nested path support (`MDCONTEXT_SEARCH_LIMIT` maps to `search.limit`). Use `Config.nested("mdcontext")` pattern.
+
+**Why it matters**: Standard pattern for CI/CD integration and containerized environments. Keeps secrets out of config files.
+
+---
+
+### Task 9: Use Effect Redacted for API Keys
+
+**Priority**: Medium
+**Effort**: Small (1-2 hours)
+**Dependencies**: None
+
+**Description**: Replace `process.env.OPENAI_API_KEY` with `Config.redacted("OPENAI_API_KEY")`. Update `OpenAIProvider` to accept `Redacted<string>` and use `Redacted.value()` only when making API calls.
+
+**Why it matters**: Prevents API keys from appearing in logs or error messages. Effect's `Redacted` type shows `<redacted>` when stringified.
+
+---
+
+## Phase 4: Validation & Errors
+
+### Task 10: Implement User-friendly Config Errors
+
+**Priority**: High
+**Effort**: Medium (4-8 hours)
+**Dependencies**: Task 3
+
+**Description**: Create a custom error formatter for `ConfigError` that shows file location, expected type, actual value, and hints. Use `Effect.catchTag("ConfigError", ...)` to intercept and format errors before CLI output.
+
+**Why it matters**: Good error messages dramatically reduce user frustration. Config errors should guide users to the fix, not just report the problem.
+
+---
+
+### Task 11: Add config check Subcommand
+
+**Priority**: Low
+**Effort**: Small (2-4 hours)
+**Dependencies**: Task 10
+
+**Description**: Create `mdcontext config check` that validates configuration and displays the effective merged config from all sources (file, env, defaults).
+
+**Why it matters**: Useful for debugging config issues and CI/CD validation. Shows users what config values are actually in effect.
+
+---
+
+## Phase 5: Testing Infrastructure
+
+### Task 12: Create Config Testing Utilities
+
+**Priority**: Medium
+**Effort**: Small (2-4 hours)
+**Dependencies**: Task 2
+
+**Description**: Export `TestConfigLayer` helpers that provide mock config via `Layer.succeed(ConfigService, {...})`. Create `withTestConfig(overrides)` utility for partial config in tests.
+
+**Why it matters**: Enables isolated testing without environment pollution. Tests can run in parallel with different configs.
+
+---
+
+### Task 13: Add Config Integration Tests
+
+**Priority**: Medium
+**Effort**: Medium (4-8 hours)
+**Dependencies**: Task 12, Task 4
+
+**Description**: Write integration tests verifying: (1) CLI flags override config file, (2) env vars override config file, (3) config file overrides defaults, (4) invalid config produces friendly errors.
+
+**Why it matters**: Validates the precedence chain works correctly. Catches regressions in config handling.
+
+---
+
+## Phase 6: Consolidation & Cleanup
+
+### Task 14: Extract Hardcoded Constants to Config
+
+**Priority**: Medium
+**Effort**: Medium (1-2 days)
+**Dependencies**: Task 5
+
+**Description**: Move hardcoded values from `summarizer.ts` (TOKEN_BUDGETS, compression ratios), `openai-provider.ts` (model, batch size), `searcher.ts` (limits, thresholds), and other files to ConfigService. Keep constants as defaults in the Config definition.
+
+**Why it matters**: Enables user customization of currently hardcoded behavior. Centralizes "magic numbers" for easier maintenance.
+
+---
+
+### Task 15: Version from package.json
+
+**Priority**: Low
+**Effort**: Small (1-2 hours)
+**Dependencies**: None
+
+**Description**: Replace hardcoded `'0.1.0'` in `main.ts` and `mcp/server.ts` with dynamic version read from `package.json`. Use `Effect.sync(() => require('../package.json').version)` or import assertion.
+
+**Why it matters**: Version should match package.json automatically. Eliminates manual version sync across files.
+
+---
+
+## Phase 7: Documentation
+
+### Task 16: Document Configuration System
+
+**Priority**: High
+**Effort**: Medium (4-8 hours)
+**Dependencies**: Task 5
+
+**Description**: Create configuration documentation covering: all options with descriptions, TypeScript config file example, environment variable mapping, precedence explanation, and migration guide from CLI-only usage.
+
+**Why it matters**: Users can't use features they don't know about. Good docs reduce support burden and establish mdcontext as a professional tool.
+
+---
+
+## Summary
+
+| Phase              | Tasks      | Effort | Priority Focus |
+| ------------------ | ---------- | ------ | -------------- |
+| 1. Foundation      | 1, 2, 3, 4 | Medium | High           |
+| 2. CLI Integration | 5, 6, 7    | Medium | High/Medium    |
+| 3. Environment     | 8, 9       | Small  | Medium         |
+| 4. Validation      | 10, 11     | Medium | High/Low       |
+| 5. Testing         | 12, 13     | Medium | Medium         |
+| 6. Cleanup         | 14, 15     | Medium | Medium/Low     |
+| 7. Documentation   | 16         | Medium | High           |
+
+### Recommended MVP (Minimum Viable Configuration)
+
+**Tasks 1, 2, 3, 4, 5, 10, 16**
+
+This provides:
+
+- Working Effect Config with Layer
+- Config file support
+- CLI integration with precedence
+- Friendly error messages
+- Documentation
+
+---
+
+## Dependencies Graph
+
+```
+Task 1 (Config Schema) ────┬─► Task 2 (ConfigService Layer) ─► Task 5 (CLI Integration)
+                           │                                    │
+                           │                                    ├─► Task 6 (--config flag)
+                           │                                    │
+                           ├─► Task 3 (File ConfigProvider) ───┼─► Task 4 (Precedence Chain)
+                           │           │                        │
+                           │           └─► Task 7 (config init) │
+                           │                                    │
+                           ├─► Task 8 (Env Vars)               └─► Task 14 (Extract Constants)
+                           │
+                           └─► Task 16 (Documentation)
+
+Task 2 (Layer) ─► Task 12 (Test Utils) ─► Task 13 (Integration Tests)
+
+Task 3 (File Provider) ─► Task 10 (Error Formatting) ─► Task 11 (config check)
+
+Task 9 (Redacted) ──── Independent
+Task 15 (Version) ──── Independent
+```
+
+---
+
+## Tasks Removed from Original List
+
+The following tasks from `03-task-candidates.md` are **not applicable** given Effect is already in use:
+
+- **1.1 Define Configuration Schema with Zod** - Replaced by Effect Config (Task 1)
+- **1.2 Create defineConfig Helper** - Still useful but implementation differs (included in Task 7)
+- **1.3 Implement Config Loader with c12** - Replaced by Effect ConfigProvider (Task 3)
+- **5.2 Add Schema-Based Config Type Generation** - Effect Config provides this natively
+
+---
+
+_Created: 2026-01-21_

package/research/dogfood/consolidated-tool-evaluation.md

@@ -0,0 +1,373 @@
+# Consolidated Tool Evaluation Report: mdcontext
+
+## 1. Executive Summary
+
+**Overall Verdict**: The mdcontext tool is **highly effective for structured documentation research** with an average rating of **4.06/5** across all three strategies (15 total agents). The tool successfully enabled exploration of a ~207K token documentation corpus while reading only 25-30% of raw content through targeted extraction.
+
+**Key Strengths**: The `tree`, `context --section`, and keyword `search` commands form a powerful workflow for systematic documentation analysis. Token-aware budgeting and section-level extraction are major differentiators.
+
+**Key Weaknesses**: Multi-word search failures, 10-result cap without pagination, and unreliable semantic search for conceptual queries are the primary blockers to broader adoption.
+
+**Bottom Line**: Recommended for structured markdown documentation research. Critical improvements needed in search capabilities to unlock full potential.
+
+---
+
+## 2. Aggregate Scores
+
+### By Strategy
+
+| Strategy | Methodology        | Agents | Avg Rating    | Confidence  | Total Commands |
+| -------- | ------------------ | ------ | ------------- | ----------- | -------------- |
+| A        | Divide by Folder   | 3      | 4/5 (implied) | Medium-High | ~100 (est.)    |
+| B        | Divide by Question | 3      | 4/5           | High (3/3)  | 114            |
+| C        | Explore-Then-Dive  | 6      | 4.17/5        | High (6/6)  | 175            |
+
+### Individual Agent Scores (Where Available)
+
+| Agent | Strategy | Rating | Confidence |
+| ----- | -------- | ------ | ---------- |
+| B1    | B        | 4/5    | Medium     |
+| B2    | B        | 4/5    | High       |
+| B3    | B        | 4/5    | High       |
+| C1    | C        | 4/5    | High       |
+| C2    | C        | 4/5    | High       |
+| C3    | C        | 4/5    | High       |
+| C4    | C        | 4/5    | High       |
+| C5    | C        | 5/5    | High       |
+| C6    | C        | 4/5    | High       |
+
+**Overall Average**: **4.06/5** (weighted by available ratings)
+**Confidence Distribution**: 11/12 High, 1/12 Medium
+
+---
+
+## 3. What Worked Well (Consensus)
+
+Features praised across multiple strategies, with frequency counts:
+
+| Feature                                                    | Strategy A | Strategy B | Strategy C | Total Mentions | Notes                                                         |
+| ---------------------------------------------------------- | ---------- | ---------- | ---------- | -------------- | ------------------------------------------------------------- |
+| `mdcontext tree` - Document structure with token counts    | 3/3        | 3/3        | 6/6        | **12/12**      | "Perfect for planning", "Invaluable for prioritization"       |
+| `mdcontext context --section` - Precise section extraction | 3/3        | 3/3        | 5/6        | **11/12**      | "Game-changer", "Surgical extraction", 44-61% token reduction |
+| `mdcontext search` - Fast keyword discovery                | 3/3        | 3/3        | 6/6        | **12/12**      | "Found relevant content quickly", "Good context lines"        |
+| Token budgeting (`-t` flag)                                | 3/3        | 3/3        | 2/6        | **8/12**       | "Respects limits while showing included/excluded"             |
+| `mdcontext stats` - Quick index overview                   | 2/3        | 2/3        | 3/6        | **7/12**       | "Instant scope understanding"                                 |
+| Boolean search operators (AND/OR/quoted phrases)           | 2/3        | 0/3        | 2/6        | **4/12**       | "Worked as expected"                                          |
+| Fast indexing speed                                        | 1/3        | 1/3        | 0/6        | **2/12**       | 535ms for 23 docs, ~$0.003 cost                               |
+| `mdcontext context --sections` - Section listing           | 0/3        | 0/3        | 4/6        | **4/12**       | "Essential for finding exact section names"                   |
+
+### Consensus Highlights
+
+1. **Universal Praise (All 3 Strategies)**:
+   - `tree` command for understanding document structure
+   - `context --section` for targeted extraction
+   - Basic keyword `search` functionality
+   - Token budget control
+
+2. **The Optimal Workflow Pattern** (emerged from Strategy C):
+   1. `mdcontext tree <file>` - See structure and token counts
+   2. `mdcontext context --sections <file>` - Get exact section names
+   3. `mdcontext context <file> --section "X"` - Extract needed sections
+   4. `mdcontext search "term"` - Find cross-references
+   5. Repeat as needed
+
+---
+
+## 4. What Was Frustrating (Consensus)
+
+Pain points identified across multiple strategies, with frequency counts:
+
+| Issue                                           | Strategy A | Strategy B | Strategy C | Total Mentions | Severity |
+| ----------------------------------------------- | ---------- | ---------- | ---------- | -------------- | -------- |
+| Multi-word search returns 0 results             | 0/3        | 3/3        | 5/6        | **8/12**       | High     |
+| Semantic search unreliable/returns 0 results    | 3/3        | 3/3        | 4/6        | **10/12**      | High     |
+| Search results capped at 10, no pagination      | 2/3        | 0/3        | 4/6        | **6/12**       | High     |
+| Directory-scoped search broken                  | 3/3        | 0/3        | 0/6        | **3/12**       | Medium   |
+| Section name requires exact match               | 0/3        | 0/3        | 3/6        | **3/12**       | Medium   |
+| Token truncation unclear/unpredictable          | 1/3        | 3/3        | 2/6        | **6/12**       | Medium   |
+| Cannot search within specific file              | 0/3        | 0/3        | 2/6        | **2/12**       | Low      |
+| Cannot request multiple sections in one command | 0/3        | 0/3        | 2/6        | **2/12**       | Low      |
+| Context command syntax confusion                | 0/3        | 0/3        | 3/6        | **3/12**       | Low      |
+| No way to chain or aggregate searches           | 0/3        | 3/3        | 0/6        | **3/12**       | Medium   |
+| False positives in keyword search               | 0/3        | 2/3        | 0/6        | **2/12**       | Low      |
+
+### Critical Issues (Blocking Workflows)
+
+1. **Semantic Search Failure** (10/12 mentions)
+   - "All three agents found semantic search unreliable for multi-word conceptual queries"
+   - "All fell back to keyword search frequently"
+   - "Strongest cross-agent signal about the mdcontext tool"
+   - Root cause: Multi-word queries like "failure automation", "job context" return 0 results
+
+2. **Search Result Cap** (6/12 mentions)
+   - "Hard to know if important results are being missed"
+   - "No pagination"
+   - "Sometimes wanted more matches"
+
+3. **Directory-Scoped Search Broken** (3/12 mentions, but all in Strategy A)
+   - `mdcontext search "term" docs/` fails with "No index found" even when index exists
+   - Critical for multi-folder repositories
+
+---
+
+## 5. What Was Missing (Consensus)
+
+Feature requests and gaps identified, with frequency counts:
+
+| Missing Feature                                       | Strategy A | Strategy B | Strategy C | Total Mentions |
+| ----------------------------------------------------- | ---------- | ---------- | ---------- | -------------- |
+| Local embedding option (no OpenAI API required)       | 2/3        | 0/3        | 0/6        | **2/12**       |
+| Configurable/unlimited search results                 | 2/3        | 0/3        | 4/6        | **6/12**       |
+| Fuzzy/stemmed search ("fail" finds "failure")         | 1/3        | 3/3        | 3/6        | **7/12**       |
+| Cross-file/multi-file operations                      | 2/3        | 2/3        | 1/6        | **5/12**       |
+| Search within results / progressive refinement        | 0/3        | 3/3        | 0/6        | **3/12**       |
+| Hybrid semantic+keyword search mode                   | 0/3        | 3/3        | 0/6        | **3/12**       |
+| Export/save functionality                             | 0/3        | 3/3        | 0/6        | **3/12**       |
+| Cross-reference navigation                            | 1/3        | 1/3        | 1/6        | **3/12**       |
+| Relevance ranking for search results                  | 1/3        | 0/3        | 0/6        | **1/12**       |
+| Section exclusion in context                          | 1/3        | 0/3        | 0/6        | **1/12**       |
+| "What's undefined" query (terms used but not defined) | 0/3        | 1/3        | 0/6        | **1/12**       |
+| Duplicate content detection                           | 0/3        | 0/3        | 1/6        | **1/12**       |
+| AI-generated summaries of search results              | 1/3        | 0/3        | 0/6        | **1/12**       |
+| Diff between documents                                | 1/3        | 0/3        | 0/6        | **1/12**       |
+| Semantic search threshold adjustment                  | 0/3        | 2/3        | 0/6        | **2/12**       |
+| Context around keyword matches without re-running     | 0/3        | 1/3        | 0/6        | **1/12**       |
+| Batch context extraction for multiple sections/files  | 0/3        | 1/3        | 2/6        | **3/12**       |
+| "Related sections" feature                            | 0/3        | 1/3        | 0/6        | **1/12**       |
+
+---
+
+## 6. Feature-Specific Feedback
+
+### 6.1 `mdcontext tree`
+
+**Rating**: Excellent (12/12 positive mentions)
+
+**What Works**:
+
+- Document outlines with token counts per section
+- "Perfect for planning", "Invaluable for prioritization"
+- Fast execution
+- Helps identify which sections are worth extracting
+
+**Issues**:
+
+- Section numbering inconsistency: tree shows "## 1. Section" but context uses "1.1" notation (Strategy A)
+- No option to see nested depth limits
+
+**Recommendations**:
+
+- Maintain as-is; this is the strongest feature
+- Consider adding depth limit option for very deep documents
+
+---
+
+### 6.2 `mdcontext search`
+
+**Rating**: Mixed (keyword good, semantic problematic)
+
+#### Keyword Search
+
+**What Works**:
+
+- Reliable and essential fallback when semantic search fails
+- Boolean operators (AND/OR/quoted phrases) work well
+- Good context lines around matches
+
+**Issues**:
+
+- Multi-word searches fail: "failure automation", "job context", "pause resume terminate" return 0 results (8/12 mentions)
+- 10 result cap with no pagination (6/12 mentions)
+- Cannot search within specific file or directory (5/12 mentions)
+- No stemmed/fuzzy matching: "suggest" doesn't find "suggestion" (7/12 mentions)
+- False positives reported (2/12 mentions)
+
+#### Semantic Search
+
+**What Works**:
+
+- Fast embedding indexing (~$0.003 cost)
+- Works better for concrete concepts (workflows, collaboration) than abstract critiques (gaps, criticisms) (Strategy B observation)
+
+**Issues**:
+
+- Returns 0 results for multi-word conceptual queries (10/12 mentions)
+- Requires external API key (OpenAI) - barrier to adoption (2/12 mentions)
+- No threshold adjustment available
+- All agents fell back to keyword search frequently
+
+**Critical Observation** (Strategy B):
+
+> "B3 (workflows) used semantic search exclusively and found it more effective for their domain. B1 and B2 heavily relied on keyword search after semantic search failed. This suggests semantic search may work better for concrete concepts (workflows, collaboration) than abstract critiques (gaps, criticisms)."
+
+---
+
+### 6.3 `mdcontext context`
+
+**Rating**: Very Good (11/12 positive mentions for `--section`)
+
+**What Works**:
+
+- Precise section extraction with `--section` flag
+- 44-61% token reduction while preserving key content
+- Token budgeting with `-t` flag
+- `--sections` flag for listing available sections
+
+**Issues**:
+
+- Section name requires exact match (3/12 mentions)
+- Token truncation unpredictable/unclear (6/12 mentions)
+  - "100% reduction on small files" (Strategy A)
+  - "36% shown with no explicit warning" (Strategy C)
+- Context duplication: `--section "Time Travel"` returned same section twice (parent and subsection) (Strategy A)
+- Cannot request multiple sections in one command (2/12 mentions)
+- Initial syntax confusion (positional arguments vs flags) (3/12 mentions)
+
+**Recommendations**:
+
+- Add fuzzy/partial section name matching
+- Add explicit "section won't fit" warning
+- Support multiple `--section` flags in one command
+- Fix duplication bug
+
+---
+
+### 6.4 `mdcontext stats`
+
+**Rating**: Good (7/12 positive mentions)
+
+**What Works**:
+
+- Quick overview of index size and distribution
+- "Instant scope understanding"
+- Useful for understanding corpus size before diving in
+
+**Issues**:
+
+- No specific issues reported
+
+---
+
+### 6.5 `mdcontext index`
+
+**Rating**: Good (2/12 explicit mentions, but used by all)
+
+**What Works**:
+
+- Fast: 535ms for 23 docs
+- Low cost: ~$0.003 for embeddings
+- Required for search to work
+
+**Issues**:
+
+- Directory-scoped search fails even with existing index (Strategy A - all 3 agents)
+- Semantic search unreliability may be an indexing issue
+
+---
+
+## 7. Priority Improvements
+
+### P0 (Critical): Mentioned by All 3 Strategies
+
+| Issue                                                        | Impact                                    | Recommendation                                                                           |
+| ------------------------------------------------------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **Semantic search returns 0 results for multi-word queries** | Agents abandoned semantic search entirely | Debug and fix multi-word query handling; consider hybrid mode that falls back to keyword |
+| **10 result limit with no pagination**                       | Users miss important results              | Add configurable limit (`--limit 50`) and/or pagination                                  |
+| **Multi-word keyword search fails**                          | Basic search workflows broken             | Support phrase matching by default; document quoting requirements                        |
+
+### P1 (High): Mentioned by 2 Strategies
+
+| Issue                                 | Strategies     | Recommendation                                                         |
+| ------------------------------------- | -------------- | ---------------------------------------------------------------------- |
+| **Token truncation unclear**          | A, B           | Add explicit warning when content is truncated; show what was excluded |
+| **Directory-scoped search broken**    | A (all agents) | Fix path filtering: `mdcontext search "term" docs/` should work        |
+| **No fuzzy/stemmed search**           | B, C           | Add stemming support: "suggest" should match "suggestion"              |
+| **No cross-file operations**          | A, B           | Add batch context extraction: `mdcontext context docs/*.md -t 10000`   |
+| **Section name requires exact match** | B, C           | Add fuzzy section name matching                                        |
+
+### P2 (Medium): Mentioned by 1 Strategy but Significant Impact
+
+| Issue                                | Strategy | Recommendation                                                                           |
+| ------------------------------------ | -------- | ---------------------------------------------------------------------------------------- |
+| **No local embedding option**        | A        | Support local embedding models (e.g., sentence-transformers) to remove OpenAI dependency |
+| **No search within results**         | B        | Add progressive refinement: search within previous results                               |
+| **Cannot request multiple sections** | C        | Support multiple `--section` flags: `--section "A" --section "B"`                        |
+| **Context command syntax confusion** | C        | Improve help text and error messages for positional vs flag arguments                    |
+| **No hybrid semantic+keyword mode**  | B        | Auto-fall back to keyword when semantic returns 0 results                                |
+| **No relevance ranking**             | A        | Sort results by relevance, not document order                                            |
+| **No export/save functionality**     | B        | Add `--output` flag to save results to file                                              |
+| **Context duplication bug**          | A        | Fix `--section` returning parent and child when names overlap                            |
+
+---
+
+## 8. Methodology Comparison
+
+### Which Strategy Found the Tool Most Effective?
+
+**Strategy C (Explore-Then-Dive)**: 4.17/5 average, 100% high confidence
+
+Strategy C found the tool most effective because:
+
+1. **Systematic workflow**: The two-phase approach (map then dive) matched the tool's strengths
+2. **Single-file focus**: Divers could use `tree` -> `context --sections` -> `context --section` workflow effectively
+3. **Clear boundaries**: Each diver had a focused theme, reducing need for cross-file operations
+4. **High command efficiency**: 96% of 175 commands were useful
+
+### Which Strategy Found the Tool Least Effective?
+
+**Strategy B (Divide by Question)**: 4/5 average, but most frustration expressed
+
+Strategy B found the tool least effective because:
+
+1. **Question-based research requires cross-cutting search**: Agents needed to find concepts across all files
+2. **Heavy reliance on search**: 69 of 114 commands were searches (vs. context extraction)
+3. **Semantic search failures most pronounced**: All 3 agents explicitly noted semantic search unreliability
+4. **Abstract queries**: Questions like "gaps" and "criticisms" don't map well to keyword search
+
+### Key Insight
+
+The tool works best for **systematic, file-by-file exploration** (Strategy C) and struggles with **cross-cutting conceptual queries** (Strategy B). This suggests prioritizing:
+
+1. Better semantic search for conceptual exploration
+2. Cross-file operations for question-based research
+3. Maintaining the excellent tree/context workflow for deep dives
+
+---
+
+## 9. Actionable Summary
+
+### Immediate Fixes (This Sprint)
+
+1. Fix multi-word semantic search returning 0 results
+2. Add `--limit` flag to search command
+3. Fix directory-scoped search path filtering
+
+### Short-Term Improvements (Next 2-4 Weeks)
+
+1. Add fuzzy/stemmed keyword search
+2. Add explicit truncation warnings
+3. Support multiple `--section` flags
+4. Add hybrid semantic+keyword search mode
+
+### Medium-Term Enhancements (Next Quarter)
+
+1. Add local embedding support (remove OpenAI dependency)
+2. Add cross-file batch operations
+3. Add search-within-results / progressive refinement
+4. Add relevance ranking
+5. Add export functionality
+
+### Maintain (Do Not Regress)
+
+1. `tree` command with token counts
+2. `context --section` precise extraction
+3. Token budgeting (`-t` flag)
+4. Fast indexing
+5. Boolean search operators
+
+---
+
+_Report generated from Strategy A, B, and C synthesis reports_
+_Total agents contributing: 12 (3 + 3 + 6)_
+_Total commands analyzed: ~389 (100 + 114 + 175)_
+_Documentation corpus: ~207K tokens across 23 files_