multi-stage matching upgrades

Author: Nathan Parker

docs/CLI/index.md

@@ -934,8 +934,14 @@ You can also explicitly specify the domain using the `--domain` option.
 - `--location TEXT` - Filter by location (city, country, or region)
 - `--capabilities TEXT` - Comma-separated list of required capabilities
 - `--materials TEXT` - Comma-separated list of required materials
-- `--min-confidence FLOAT` - Minimum confidence threshold (0.0-1.0, default: 0.7)
+- `--min-confidence FLOAT` - Minimum confidence threshold (0.0-1.0, default: 0.3)
 - `--max-results INTEGER` - Maximum number of results (default: 10)
+- `--max-depth INTEGER` - BOM matching depth (0 = single-level, >0 = nested component matching)
+- `--auto-detect-depth` - Auto-enable nested matching when manifest contains nested components
+- `--allow-facility-combinations` - Enable aggregated multi-facility matching for manufacturing
+- `--max-facilities-per-solution INTEGER` - Cap facilities used in one composite solution (default: 3)
+- `--combination-strategy [greedy]` - Composite solver strategy
+- `--no-alternative-solutions` - Return only the top composite solution
 - `--output, -o TEXT` - Output file path
 - `--use-llm` - Enable LLM integration for enhanced matching
 - `--llm-provider [anthropic|openai|google|azure|local]` - LLM provider
@@ -969,6 +975,12 @@ ohm match requirements my-design.okh.json --min-confidence 0.9
 # Match with LLM enhancement
 ohm match requirements my-design.okh.json --use-llm --quality-level professional
 
+# Composite matching across multiple facilities
+ohm match requirements my-design.okh.json --allow-facility-combinations --max-facilities-per-solution 3
+
+# Composite matching returning only best solution
+ohm match requirements my-design.okh.json --allow-facility-combinations --no-alternative-solutions
+
 # Save results to file
 ohm match requirements my-design.okh.json --output matches.json
 ```
@@ -980,6 +992,7 @@ The command displays matching facilities with:
 - Confidence score
 - Match type (manufacturing or cooking)
 - Location (if available)
+- Structured summary metadata (`match_summary`, `coverage_gaps`) in JSON mode
 
 **Note:** Facility IDs are displayed as full UUIDs. Use the full ID with `ohm okw get` to retrieve facility details.
 

docs/api/routes.md

@@ -1151,7 +1151,13 @@ The endpoint automatically detects the domain from the input data:
 
   // Optional Matching Parameters
   "min_confidence": 0.5,
-  "max_results": 10
+  "max_results": 10,
+
+  // Facility-combination controls (API-first)
+  "allow_facility_combinations": false,
+  "max_facilities_per_solution": 3,
+  "return_alternative_solutions": true,
+  "combination_strategy": "greedy"
 }
 ```
 
@@ -1218,6 +1224,11 @@ The endpoint returns a wrapped response with the following structure:
 - `total_solutions`: Total number of matching solutions found
 - `matching_metrics`: Breakdown of match types
 - `validation_results`: Validation results for each solution
+- `match_summary`: Structured summary object for API consumers (mode, counts, coverage, and combination flags)
+- `coverage_gaps`: Uncovered process requirements, if any
+- `match_summary_text`: Human-readable rendering of `match_summary` (for logs and quick inspection)
+  - `match_summary.coverage_gap_counts`: Multiplicity of each uncovered requirement
+  - `match_summary.warnings`: Non-fatal warnings (e.g. composite fallback to single-facility matching)
 
 **Status:**  **Fully Implemented** - **Complete matching engine with Azure Blob Storage integration**