phase 2 complete

Author: Nathan Parker

docs/CLI/index.md

@@ -942,6 +942,7 @@ You can also explicitly specify the domain using the `--domain` option.
 - `--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
+- `--explain` - Include structured and human-readable per-solution explanations in output
 - `--output, -o TEXT` - Output file path
 - `--use-llm` - Enable LLM integration for enhanced matching
 - `--llm-provider [anthropic|openai|google|azure|local]` - LLM provider
@@ -952,6 +953,9 @@ You can also explicitly specify the domain using the `--domain` option.
 - `--table` - Output results in table format
 - `--verbose, -v` - Enable verbose output
 
+**Verbose behavior note:**
+- In `match requirements`, `--verbose` automatically enables explanation output (equivalent to `--explain`) so diagnostics are consistently shown during interactive debugging.
+
 **Examples:**
 ```bash
 # Match OKH requirements (manufacturing domain)
@@ -987,8 +991,10 @@ ohm match requirements my-design.okh.json --output matches.json
 
 **Output:**
 The command displays matching facilities with:
+- Rank (`1` = best match)
 - Facility name
 - **Full facility ID (UUID)** - required for `ohm okw get` command
+- Composite detail bundle (`facility_details`) in JSON mode when a solution spans multiple facilities
 - Confidence score
 - Match type (manufacturing or cooking)
 - Location (if available)

docs/api/routes.md

@@ -1218,9 +1218,12 @@ The endpoint returns a wrapped response with the following structure:
   - `facility`: Complete facility/kitchen information
   - `facility_id`: **Unique identifier** for the facility (required for API operations)
   - `facility_name`: Human-readable facility name
+  - `facility_ids`: List of facility IDs participating in the solution (**composite solutions only**)
+  - `facility_names`: List of facility names participating in the solution (**composite solutions only**)
+  - `facility_details`: List of `{facility_id, facility_name, facility}` objects (**composite solutions only**)
   - `match_type`: Domain type ("manufacturing" or "cooking")
   - `confidence`: Match confidence score (0.0-1.0)
-  - `rank`: Solution rank (1 = best match)
+  - `rank`: Solution rank (1 = best match, stable after confidence filtering and result limiting)
 - `total_solutions`: Total number of matching solutions found
 - `matching_metrics`: Breakdown of match types
 - `validation_results`: Validation results for each solution

docs/matching/match-explanation.md

@@ -11,6 +11,7 @@ When matching requirements to facilities, you can request **per-facility explana
   ```bash
   ohm match requirements my-design.okh.json --explain
   ```
+  In current CLI behavior, `--verbose` also enables explanation output automatically for `match requirements`.
   Explanations are printed under each facility in table output; in JSON output they appear as `explanation` and `explanation_human` on each solution.
 
 ### Manual testing with synthetic data (no server/storage)

pyproject.toml

@@ -53,6 +53,7 @@ addopts = "-v --tb=short"
 asyncio_mode = "strict"
 markers = [
     "e2e: end-to-end canonical workflow tests",
+    "integration: integration tests that may require services or seeded data",
     "slow: tests that take more than 10 seconds",
     "llm: tests requiring LLM API access",
     "benchmark: performance benchmark tests",

src/cli/match.py

@@ -269,6 +269,10 @@ async def requirements(
     cli_ctx = ctx.obj
     cli_ctx.start_command_tracking("match-requirements")
 
+    # Keep explain output aligned with verbose mode ergonomics.
+    if verbose and not include_explanation:
+        include_explanation = True
+
     # Update CLI context with parameters from decorator
     cli_ctx.update_llm_config(
         use_llm=use_llm,
@@ -575,6 +579,8 @@ async def fallback_match():
                         solutions, key=lambda s: s.score, reverse=True
                     )
                     solution_dicts = [s.to_dict() for s in solutions_list]
+                    for idx, solution_dict in enumerate(solution_dicts, start=1):
+                        solution_dict["rank"] = idx
                     total_trees = sum(len(s.all_trees) for s in solutions_list)
                     result = {
                         "solutions": solution_dicts,
@@ -684,8 +690,11 @@ async def fallback_match():
                             # Continue without failing the match
 
                     if results_list:
+                        solution_dicts = [r.to_dict() for r in results_list]
+                        for idx, solution_dict in enumerate(solution_dicts, start=1):
+                            solution_dict["rank"] = idx
                         result = {
-                            "solutions": [r.to_dict() for r in results_list],
+                            "solutions": solution_dicts,
                             "total_solutions": len(results_list),
                             "matching_mode": "single-level",
                         }
@@ -1421,7 +1430,8 @@ async def _display_match_results(
                 facility_name = solution.get("name", "Unknown Facility")
                 confidence = solution.get("confidence", solution.get("score", 0))
 
-            click.echo(f"\n{i}. {facility_name}")
+            rank = solution.get("rank", i)
+            click.echo(f"\n{rank}. {facility_name}")
 
             # Show facility ID if available
             facility_id = solution.get("facility_id")

src/core/api/routes/match.py

@@ -1956,9 +1956,18 @@ async def _perform_enhanced_matching(
                         facility_id = str(uuid4())[:8]
 
                 # Create solution dict in expected format
+                if not facility_data:
+                    facility_data = {
+                        "id": facility_id,
+                        "name": facility_name,
+                    }
+                elif isinstance(facility_data, dict):
+                    facility_data.setdefault("id", facility_id)
+                    facility_data.setdefault("name", facility_name)
+
                 solution_dict = {
                     "tree": representative_tree.to_dict(),
-                    "facility": facility_data if facility_data else {},
+                    "facility": facility_data,
                     "facility_id": facility_id,
                     "facility_name": facility_name,
                     "match_type": "manufacturing",
@@ -1987,15 +1996,34 @@ async def _perform_enhanced_matching(
                         tree_facility_id = (
                             str(tree.okw_reference) if tree.okw_reference else None
                         )
-                        if tree_facility_id:
-                            for facility in facilities:
-                                if str(getattr(facility, "id", "")) == tree_facility_id:
-                                    tree_facility_data = (
-                                        facility.to_dict()
-                                        if hasattr(facility, "to_dict")
-                                        else facility
-                                    )
-                                    break
+                        for facility in facilities:
+                            if (
+                                tree_facility_id
+                                and str(getattr(facility, "id", "")) == tree_facility_id
+                            ):
+                                tree_facility_data = (
+                                    facility.to_dict()
+                                    if hasattr(facility, "to_dict")
+                                    else facility
+                                )
+                                break
+                            if (
+                                hasattr(facility, "name")
+                                and facility.name == tree.facility_name
+                            ):
+                                tree_facility_data = (
+                                    facility.to_dict()
+                                    if hasattr(facility, "to_dict")
+                                    else facility
+                                )
+                                if not tree_facility_id:
+                                    tree_facility_id = str(getattr(facility, "id", ""))
+                                break
+                        if not tree_facility_data:
+                            tree_facility_data = {
+                                "id": tree_facility_id,
+                                "name": tree.facility_name,
+                            }
                         facility_details.append(
                             {
                                 "facility_id": tree_facility_id,

src/core/services/matching_service.py

@@ -2531,7 +2531,7 @@ async def _match_component_to_facilities(
             )
         ]
 
-        # CRITICAL: Log component processes in the main message so it's always visible
+        # Log component process shape for diagnostics.
         logger.info(
             f"Matching component '{component.name}' to {len(facilities)} facilities | "
             f"Component processes: {component_processes} | "
@@ -2548,9 +2548,11 @@ async def _match_component_to_facilities(
         )
 
         if non_uri_processes:
-            logger.error(
-                f"CRITICAL: Component '{component.name}' has non-URI processes! "
-                f"non_uri_processes={non_uri_processes}, all_processes={component_processes}",
+            # Non-URI processes are expected for many manifests after normalization.
+            # Keep this visible for debugging, but do not emit as an ERROR.
+            logger.warning(
+                f"Component '{component.name}' includes non-URI process labels "
+                f"(accepted): {non_uri_processes}",
                 extra={
                     "component_id": component.id,
                     "component_name": component.name,