helpfulengineering · touchthesun · Apr 7, 2026 · Apr 7, 2026
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.yml
@@ -135,7 +135,9 @@ jobs:
             tests/api/test_match_phase1_contract.py \
             tests/api/test_relationship_endpoints.py \
             tests/api/test_solution_management_endpoints.py \
+            tests/api/test_visualization_contract_endpoints.py \
             tests/cli/test_match_cli_guidance.py \
+            tests/cli/test_match_visualize_cli.py \
             tests/cli/test_solution_commands.py \
             -m "not llm and not quarantine" \
             --maxfail=1

diff --git a/docs/CLI/index.md b/docs/CLI/index.md
@@ -1041,6 +1041,28 @@ The command displays matching facilities with:
 
 **Note:** Facility IDs are displayed as full UUIDs. Use the full ID with `ohm okw get` to retrieve facility details.
 
+### `ohm match visualize`
+
+Generate visualization artifacts from a match run.
+
+```bash
+ohm match visualize INPUT_FILE [OPTIONS]
+```
+
+**Options:**
+- `--domain [manufacturing|cooking]` - Explicit domain override
+- `--format [json|html]` - Output artifact format (default: `json`)
+- `--output, -o PATH` - Write artifact to file
+
+**Examples:**
+```bash
+# Generate JSON visualization bundle
+ohm match visualize my-design.okh.json
+
+# Generate HTML visualization report
+ohm match visualize my-design.okh.json --format html --output match-report.html
+```
+
 ### `ohm match validate`
 
 Validate a match result.
@@ -1396,6 +1418,44 @@ ohm match rules reset --confirm
 
 ---
 
+## Solution Commands
+
+Manage stored supply tree solutions and generate visualization/report artifacts.
+
+### `ohm solution visualize`
+
+Build visualization artifacts for a stored solution.
+
+```bash
+ohm solution visualize SOLUTION_ID [OPTIONS]
+```
+
+**Options:**
+- `--format [json|html]` - Output artifact format (default: `json`)
+- `--output, -o PATH` - Write artifact to file
+
+### `ohm solution report`
+
+Generate an HTML report for a stored solution.
+
+```bash
+ohm solution report SOLUTION_ID [OPTIONS]
+```
+
+**Options:**
+- `--output, -o PATH` - Write HTML report to file
+
+**Examples:**
+```bash
+# JSON visualization bundle
+ohm solution visualize 8f14e3c4-09f2-4a5e-8bd9-4b5bb5d0a9cd
+
+# HTML report
+ohm solution report 8f14e3c4-09f2-4a5e-8bd9-4b5bb5d0a9cd --output solution-report.html
+```
+
+---
+
 ## LLM Commands
 
 Manage LLM operations and AI features for enhanced OKH manifest generation and facility matching.

diff --git a/docs/api/index.md b/docs/api/index.md
@@ -56,6 +56,7 @@ For production deployments, [authentication](auth.md) can be enabled to secure A
 - **Supply Tree Generation**: Creates complete manufacturing solutions with confidence scoring
 - **Role-Oriented Human Summaries**: Supports `human_summary_profile` (`balanced`, `executive`, `analyst`) for progressive disclosure in match responses
 - **Deterministic Key Insights**: Match responses can include stable `key_insights` buckets (`risks`, `opportunities`, `recommendations`) when `include_human_summary` is enabled
+- **Visualization Contract Artifacts**: Supply-tree solutions can be exported as canonical visualization bundles and standalone HTML reports for API/CLI consumers
 
 #### API Endpoints (53 total - Fully Standardized)
 - **Match Routes (7)**: Enhanced matching with multiple input methods, filtering, and LLM support

diff --git a/docs/api/routes.md b/docs/api/routes.md
@@ -1083,6 +1083,50 @@ The supply tree in the requested format.
 
 **Status:** 📋 **Not Implemented** - Route not found in current implementation
 
+#### Solution Visualization Bundle
+
+```
+GET /v1/api/supply-tree/solution/{solution_id}/visualization
+```
+
+Builds a canonical JSON visualization bundle for a stored solution.
+
+**Response (envelope):**
+```json
+{
+  "status": "success",
+  "message": "Visualization bundle created successfully",
+  "timestamp": "2026-04-07T00:00:00Z",
+  "request_id": "req_123",
+  "data": {
+    "schema_version": "3.2.0",
+    "source_type": "supply_tree_solution",
+    "generated_at": "2026-04-07T00:00:00Z",
+    "matching": {...},
+    "supply_tree": {...},
+    "network": {...},
+    "dashboard": {...},
+    "artifacts": {...}
+  }
+}
+```
+
+#### Solution Visualization Report
+
+```
+GET /v1/api/supply-tree/solution/{solution_id}/report
+```
+
+Returns a standalone HTML report derived from the canonical visualization bundle.
+
+#### GraphML Metadata Normalization
+
+GraphML exports for supply tree and supply tree solutions include metadata comments:
+
+- `ohm_visualization_schema=3.2.0`
+- `source_type=<source>`
+- `source_id=<id>`
+
 ### Matching Routes
 
 #### Match Requirements to Capabilities (Domain-Aware)

diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md
@@ -298,7 +298,7 @@ The following items from the original Phase 2 roadmap are deferred. They have lo
 ### Overview
 OHM generates highly technical data that is difficult for humans to parse and understand. This phase focuses on making data accessible, interpretable, and actionable.
 
-**Status (April 2026): Complete for current scope. 3.1 and 3.3 are closed out; 3.2 visualization remains deferred as a separate follow-on track.**
+**Status (April 2026): Active. 3.1 and 3.3 are closed out; 3.2 visualization implementation is in progress.**
 
 ### 3.1 Data Abstraction & Summarization
 
@@ -342,28 +342,28 @@ OHM generates highly technical data that is difficult for humans to parse and un
 
 **Objective**: Create visual representations of OHM data
 
-**Status (April 2026): Deferred. Not part of the completed 3.1/3.3 closeout scope.**
+**Status (April 2026): In progress. API/CLI-first visualization artifacts and contracts are now being implemented.**
 
 #### Tasks:
-- [ ] **Matching visualization**
+- [~] **Matching visualization**
   - Facility map with match quality indicators
   - Capability coverage heat maps
   - Match confidence visualizations
   - Timeline and capacity charts
 
-- [ ] **Supply tree visualization**
+- [~] **Supply tree visualization**
   - Interactive tree diagrams
   - Process flow charts
   - Dependency graphs
   - Resource allocation views
 
-- [ ] **Network visualization**
+- [~] **Network visualization**
   - Geographic facility distribution
   - Capability network graphs
   - Production capacity maps
   - Route optimization displays
 
-- [ ] **Dashboard & reporting**
+- [~] **Dashboard & reporting**
   - Project overview dashboards
   - KPI tracking and metrics
   - Trend analysis and forecasting
@@ -420,10 +420,11 @@ OHM generates highly technical data that is difficult for humans to parse and un
 
 ---
 
-### Next Up After Phase 3
+### Next Up Inside Phase 3
 
-With Phase 3 closeout complete for the current scope, the next primary roadmap
-track is **Phase 4.1: OBM Requirements & Architecture**.
+Current priority is to complete **Phase 3.2 Data Visualization** end-to-end
+before shifting primary execution focus to **Phase 4.1: OBM Requirements &
+Architecture**.
 
 ## Phase 4: Business Logic Separation - Open Business Manager (OBM)
 

diff --git a/docs/index.md b/docs/index.md
@@ -56,6 +56,9 @@
     * [Examples](CLI/examples.md)
     * [Architecture](CLI/architecture.md)
 
+### Visualization
+* [Visualization](visualization/index.md)
+
 ### LLM Service Documentation
 * [LLM Main Documentation](llm/index.md)
 * [LLM Service Documentation](llm/llm-service.md)

diff --git a/docs/testing/harness-standards.md b/docs/testing/harness-standards.md
@@ -80,6 +80,7 @@ CI runs lanes separately in `.github/workflows/ci-cd.yml`:
 - contract lane
 - integration lane
 - contract stability guardrail suite (focused high-risk API/CLI contract files)
+  - includes visualization contract endpoints and CLI visualization commands
 
 ## Maintenance Cadence
 

diff --git a/docs/visualization/index.md b/docs/visualization/index.md
@@ -0,0 +1,65 @@
+# Visualization
+
+## Overview
+
+Phase 3.2 introduces a canonical visualization contract for API and CLI consumers.
+The first delivery path is API/CLI-first and export-oriented:
+
+- `JSONVizBundle` for machine-readable visualization payloads
+- GraphML exports for graph tooling interoperability
+- Standalone HTML reports for offline sharing
+
+## Contract
+
+Visualization payloads use schema version `3.2.0` with this top-level shape:
+
+- `schema_version`
+- `source_type` (`match_result` or `supply_tree_solution`)
+- `generated_at`
+- `matching`
+- `supply_tree`
+- `network`
+- `dashboard`
+- `artifacts`
+
+## API Endpoints
+
+### Supply Tree Visualization Bundle
+
+- `GET /v1/api/supply-tree/solution/{solution_id}/visualization`
+- Returns standard success envelope with a `data` visualization bundle payload.
+
+### Supply Tree Visualization Report
+
+- `GET /v1/api/supply-tree/solution/{solution_id}/report`
+- Returns `text/html` report generated from the same canonical visualization bundle.
+
+### GraphML Metadata Normalization
+
+GraphML exports include stable metadata comments:
+
+- `ohm_visualization_schema=3.2.0`
+- `source_type=<source>`
+- `source_id=<id>`
+
+This applies to GraphML export paths under `supply-tree` routes.
+
+## CLI Commands
+
+### Match
+
+- `ohm match visualize INPUT_FILE [--domain ...] [--format json|html] [--output PATH]`
+
+### Solution
+
+- `ohm solution visualize SOLUTION_ID [--format json|html] [--output PATH]`
+- `ohm solution report SOLUTION_ID [--output PATH]`
+
+## Implementation Notes
+
+- Matching visualization datasets include confidence bins, coverage heatmap summaries,
+  and gap/guidance projections.
+- Supply-tree datasets include nodes, edges, dependency graph, and production sequence.
+- Network datasets include facility distribution and capability adjacency with explicit
+  placeholder status for route optimization fields that are not yet available.
+