woods 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab164a85b76d9c97fc6142836da5349a444e9c62f507622fb327f5cc8f434ed4
-  data.tar.gz: 66752a95ddb4183a6f78d47417690242cfc3ad2bdfc622b8740fe2fbc388658e
+  metadata.gz: 927abae1f4f641405384261569e1d25f94a672ca986d1c50093b3f6a56b7db38
+  data.tar.gz: fa35b4320669d195a8e4f377400b6999e735aebf5447071ee3353eaa8856840b
 SHA512:
-  metadata.gz: 2d53024eefb62544ba536f23b1c9f36bebab988fc75223ef72e1d2ffd1d2ed0b46b2507781b040726b8059d14c9f6eefa3faa1c4d6b0a4b6c5019905ef41675d
-  data.tar.gz: 8d5c7a1e7ab4c7b401e61140a9ec5bea06848244d08192f05b0cc088a93980b3208cf3f22a0319545857051dc0b2a234f4d4c2ef8a5789ef108080f179aa6f99
+  metadata.gz: 5ae6ef3436f6aa6b936b46103480e797a8a6e0fb4250f5dcc8bc721c2b9b911739e5d5aebd5b8b97c6788d58dcd19e9dbd5c6211a3400283e60084ce80c6d031
+  data.tar.gz: 6b38946aca86d407ab6d516d32dda4c5797adfcd27249b1685bdebb249ff34e71d62e3eabb266c991d1b32ad2df815e2a56dc924615c1def9df0c4c6754cd629

data/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-03-27
+
+### Added
+
+- **Unblocked Documents API exporter** — sync extraction data to an Unblocked collection for code review and Q&A context
+  - `Woods::Unblocked::Client` — REST client with retry and daily budget rate limiting
+  - `Woods::Unblocked::DocumentBuilder` — type-specific Markdown formatters optimized for review context (blast radius, entry points, associations, side effects)
+  - `Woods::Unblocked::Exporter` — full/partial sync orchestrator with priority ordering
+  - `Woods::Unblocked::RateLimiter` — daily budget tracking (1000 calls/day)
+  - New rake tasks: `woods:unblocked_sync` (alias: `woods:relay`)
+  - New config: `unblocked_api_token`, `unblocked_collection_id`, `unblocked_repo_url`
+  - Integration guide: `docs/UNBLOCKED_INTEGRATION.md`
+- **Domain cluster detection** in `GraphAnalyzer` — groups code units into semantic domains using namespace prefixes and graph connectivity
+  - `GraphAnalyzer#domain_clusters` — hybrid namespace + graph clustering with hub identification, entry point detection, and boundary edge mapping
+  - New MCP tool: `domain_clusters` with `min_size` and `types` filters
+  - New renderer: `render_domain_clusters` in MarkdownRenderer
+
 ## [0.3.1] - 2026-03-04
 
 ### Fixed

data/README.md

@@ -65,6 +65,40 @@ Woods boots your Rails app, introspects everything using runtime APIs, and write
 
 Your `User` model includes `Auditable`, `Searchable`, and `SoftDeletable`. An AI tool reading `app/models/user.rb` sees 40 lines. Woods inlines all three concerns directly into the extracted unit — the AI sees the full 200-line behavioral surface area in one block.
 
+```ruby
+# What your AI sees (app/models/user.rb) — 4 lines:
+class User < ApplicationRecord
+  include Auditable
+  include Searchable
+end
+
+# What Woods produces — full source with schema + inlined concerns:
+# == Schema Information
+# email    :string           not null
+# name     :string
+#
+# class User < ApplicationRecord
+#   include Auditable
+#   include Searchable
+#   validates :email, presence: true, uniqueness: true
+#   ...
+# end
+#
+# ┌─────────────────────────────────────────────────────────────────────┐
+# │ Included from: Auditable                                            │
+# └─────────────────────────────────────────────────────────────────────┘
+#   def audit_trail ...
+# ─────────────────────────── End Auditable ───────────────────────────
+#
+# ┌─────────────────────────────────────────────────────────────────────┐
+# │ Included from: Searchable                                           │
+# └─────────────────────────────────────────────────────────────────────┘
+#   scope :search, ->(q) { where("name ILIKE ?", "%#{q}%") }
+# ─────────────────────────── End Searchable ───────────────────────────
+```
+
+The `metadata[:inlined_concerns]` array lists which concerns were resolved, so retrieval can filter by concern inclusion.
+
 ### Schema Prepending
 
 Model source gets a header with actual column types, indexes, and foreign keys pulled from the live database. No more guessing whether `name` is a `string` or `text`, or whether there's an index on `email`.
@@ -83,6 +117,122 @@ Controller source gets a route map prepended showing the real HTTP verb + path +
 
 ---
 
+## Examples
+
+### Extracted Model with Schema and Associations
+
+After extraction, each model is a self-contained JSON file with schema, associations, validations, and inlined concern source:
+
+```json
+{
+  "type": "model",
+  "identifier": "Order",
+  "file_path": "app/models/order.rb",
+  "source_code": "# == Schema Information\n# id         :bigint  not null, pk\n# user_id    :bigint  not null, fk\n# status     :string  default(\"pending\")\n# total_cents :integer\n#\nclass Order < ApplicationRecord\n  belongs_to :user\n  has_many :line_items\n  validates :status, inclusion: { in: %w[pending paid shipped] }\n  ...\nend\n\n# ┌───────────────────────────────────────────────────────────────────┐\n# │ Included from: Auditable                                          │\n# └───────────────────────────────────────────────────────────────────┘\n#   module Auditable\n#     ...\n#   end\n# ──────────────────────── End Auditable ────────────────────────────",
+  "metadata": {
+    "associations": [
+      { "type": "belongs_to", "name": "user", "target": "User" },
+      { "type": "has_many", "name": "line_items", "target": "LineItem" }
+    ],
+    "validations": [
+      { "attribute": "status", "type": "inclusion", "options": { "in": ["pending", "paid", "shipped"] } }
+    ],
+    "enums": { "status": { "pending": 0, "active": 1, "shipped": 2 } },
+    "scopes": [{ "name": "active", "source": "-> { where(status: :active) }" }],
+    "inlined_concerns": ["Auditable"]
+  },
+  "dependencies": [
+    { "type": "model", "target": "User", "via": "belongs_to" },
+    { "type": "model", "target": "LineItem", "via": "has_many" }
+  ]
+}
+```
+
+### Callback Chain with Side-Effects
+
+Woods resolves the full callback chain in execution order and detects side-effects — which columns get written, which jobs get enqueued, which mailers fire:
+
+```json
+"callbacks": [
+  { "type": "before_validation", "filter": "normalize_email", "kind": "before", "conditions": {} },
+  { "type": "before_save", "filter": "set_slug", "kind": "before", "conditions": {},
+    "side_effects": { "columns_written": ["slug"], "jobs_enqueued": [], "services_called": [], "mailers_triggered": [], "database_reads": [], "operations": [] } },
+  { "type": "after_commit", "filter": "send_welcome", "kind": "after", "conditions": {},
+    "side_effects": { "columns_written": [], "jobs_enqueued": ["WelcomeEmailJob"], "services_called": [], "mailers_triggered": ["UserMailer"], "database_reads": [], "operations": [] } }
+]
+```
+
+Side-effects are detected by `CallbackAnalyzer`, which scans callback method bodies for patterns like `self.col =` (column writes), `perform_later` (job enqueues), and `deliver_later` (mailer triggers). This is the #1 thing AI tools get wrong about Rails models.
+
+### Route-to-Controller Lookup
+
+Every route becomes its own `ExtractedUnit` with the controller and action bound from the live routing table:
+
+```json
+{
+  "type": "route",
+  "identifier": "POST /checkout",
+  "metadata": {
+    "controller": "orders",
+    "action": "create",
+    "route_name": "checkout"
+  }
+}
+```
+
+To find which controller handles a URL, use the MCP `search` tool:
+
+```json
+{ "tool": "search", "params": { "query": "/checkout", "types": ["route"] } }
+```
+
+This returns all matching route units with their controller and action — no guessing about custom routes, nested resources, or engine mount points.
+
+### Looking Up a Model's Full Structure
+
+Use the MCP `lookup` tool to get a model's complete JSON representation — schema, associations, validations, callbacks, and inlined concerns in one call:
+
+```json
+{ "tool": "lookup", "params": { "identifier": "Order", "include_source": true } }
+```
+
+Returns the full `ExtractedUnit` JSON shown in the example above, including `source_code` (with schema header and inlined concerns), `metadata` (associations, callbacks, validations, enums, scopes), `dependencies`, and `dependents`.
+
+To get just the structured metadata without source code:
+
+```json
+{ "tool": "lookup", "params": { "identifier": "Order", "include_source": false, "sections": ["metadata"] } }
+```
+
+### Finding Jobs Enqueued by a Service
+
+Use the MCP `dependencies` tool to trace what a service triggers:
+
+```json
+{ "tool": "dependencies", "params": { "identifier": "CheckoutService", "depth": 2, "types": ["job"] } }
+```
+
+Returns all job units reachable from `CheckoutService` within 2 hops — including jobs triggered indirectly via model callbacks (e.g., `CheckoutService` → `Order` → `OrderConfirmationJob`).
+
+### Runtime-Generated Method Detection
+
+Because Woods runs inside the booted Rails process, it captures every method Rails generates dynamically — enum predicates, association builders, attribute accessors, and scope methods that static analysis tools cannot see:
+
+```json
+{
+  "identifier": "Order",
+  "metadata": {
+    "enums": { "status": { "pending": 0, "active": 1, "shipped": 2 } },
+    "scopes": [{ "name": "active", "source": "-> { where(status: :active) }" }],
+    "associations": [{ "type": "has_many", "name": "line_items", "target": "LineItem" }]
+  }
+}
+```
+
+Static tools miss `status_active?`, `status_pending?`, `build_line_item`, `create_line_item!`, and dynamically registered scopes. Woods captures all of these because it queries the runtime class via `instance_methods(false)` after Rails has processed every DSL declaration.
+
+---
+
 ## Connect to Your AI Tool
 
 Woods ships two MCP servers. Most users only need the **Index Server**.
@@ -223,6 +373,26 @@ Woods is backend-agnostic. Your app database, vector store, embedding provider,
 
 See [Backend Matrix](docs/BACKEND_MATRIX.md) for supported combinations and [Configuration Reference](docs/CONFIGURATION_REFERENCE.md) for every option with defaults.
 
+### Environment-Specific Configuration
+
+```ruby
+Woods.configure do |config|
+  config.output_dir = Rails.root.join('tmp/woods')
+
+  # CI: only extract models and controllers for faster builds
+  config.extractors = %i[models controllers] if ENV['CI']
+
+  # Environment-conditional embedding provider
+  if ENV['OPENAI_API_KEY']
+    config.embedding_provider = :openai
+    config.embedding_options = { api_key: ENV['OPENAI_API_KEY'] }
+  else
+    config.embedding_provider = :ollama
+    config.embedding_options = { base_url: 'http://localhost:11434' }
+  end
+end
+```
+
 ---
 
 ## Keeping the Index Current
@@ -289,12 +459,15 @@ Everything flows through `ExtractedUnit` — the universal data structure. Each
 |-------|-----------------|
 | `identifier` | Class name or descriptive key (`"User"`, `"POST /orders"`) |
 | `type` | Category (`:model`, `:controller`, `:service`, `:job`, etc.) |
+| `file_path` | Source file location relative to Rails root |
+| `namespace` | Module namespace (`"Admin"`, `nil` for top-level) |
 | `source_code` | Annotated source with inlined concerns and schema |
 | `metadata` | Structured data — associations, callbacks, routes, fields |
 | `dependencies` | What this unit depends on (forward edges) |
 | `dependents` | What depends on this unit (reverse edges) |
 | `chunks` | Semantic sub-sections for large units |
-| `estimated_tokens` | Token count for LLM context budgeting |
+| `extracted_at` | ISO 8601 timestamp of extraction |
+| `source_hash` | SHA-256 digest for change detection |
 
 ### Output Structure
 
@@ -323,7 +496,7 @@ tmp/woods/
 │                                                                  │
 │  ┌────────────┐    ┌─────────────┐    ┌──────────────────────┐  │
 │  │  Extract   │───>│   Resolve   │───>│   Write JSON         │  │
-│  │ 34 types   │    │   graph +   │    │   per unit           │  │
+│  │ 33 types   │    │   graph +   │    │   per unit           │  │
 │  │            │    │   git data  │    │                      │  │
 │  └────────────┘    └─────────────┘    └──────────────────────┘  │
 └──────────────────────────────────────────────────────────────────┘

data/exe/woods-console-mcp

@@ -17,6 +17,10 @@ require_relative '../lib/woods/console/server'
 config_path = ENV.fetch('WOODS_CONSOLE_CONFIG', File.expand_path('~/.woods/console.yml'))
 config = File.exist?(config_path) ? YAML.safe_load_file(config_path) : {}
 
+# Suppress json-schema MultiJSON deprecation notice that would pollute stderr
+# during MCP stdio transport. The notice fires when multi_json is in the bundle.
+JSON::Validator.use_multi_json = false if defined?(JSON::Validator) && JSON::Validator.respond_to?(:use_multi_json=)
+
 server = Woods::Console::Server.build(config: config)
 transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open

data/exe/woods-mcp

@@ -19,6 +19,10 @@ require_relative '../lib/woods/mcp/bootstrapper'
 require_relative '../lib/woods/embedding/text_preparer'
 require_relative '../lib/woods/embedding/indexer'
 
+# Suppress json-schema MultiJSON deprecation notice that would pollute stderr
+# during MCP stdio transport. The notice fires when multi_json is in the bundle.
+JSON::Validator.use_multi_json = false if defined?(JSON::Validator) && JSON::Validator.respond_to?(:use_multi_json=)
+
 index_dir = Woods::MCP::Bootstrapper.resolve_index_dir(ARGV)
 retriever = Woods::MCP::Bootstrapper.build_retriever
 snapshot_store = Woods::MCP::Bootstrapper.build_snapshot_store(index_dir)

data/lib/tasks/woods.rake

@@ -618,4 +618,58 @@ namespace :woods do
 
   desc 'Send findings from the field — sync to Notion (alias for notion_sync)'
   task send: :notion_sync
+
+  desc 'Sync extraction data to Unblocked collection (Documents API)'
+  task unblocked_sync: :environment do
+    require 'woods/unblocked/exporter'
+
+    config = Woods.configuration
+    config.unblocked_api_token = ENV.fetch('UNBLOCKED_API_TOKEN', nil) || config.unblocked_api_token
+    config.unblocked_collection_id = ENV.fetch('UNBLOCKED_COLLECTION_ID', nil) || config.unblocked_collection_id
+    config.unblocked_repo_url = ENV.fetch('UNBLOCKED_REPO_URL', nil) || config.unblocked_repo_url
+
+    unless config.unblocked_api_token
+      puts 'ERROR: Unblocked API token not configured.'
+      puts 'Set UNBLOCKED_API_TOKEN env var or configure unblocked_api_token in Woods.configure.'
+      exit 1
+    end
+
+    unless config.unblocked_collection_id
+      puts 'ERROR: Unblocked collection ID not configured.'
+      puts 'Set UNBLOCKED_COLLECTION_ID env var or configure unblocked_collection_id in Woods.configure.'
+      exit 1
+    end
+
+    unless config.unblocked_repo_url
+      puts 'ERROR: Repository URL not configured.'
+      puts 'Set UNBLOCKED_REPO_URL env var or configure unblocked_repo_url in Woods.configure.'
+      puts 'Example: https://github.com/your-org/your-repo'
+      exit 1
+    end
+
+    output_dir = ENV.fetch('WOODS_OUTPUT', config.output_dir)
+
+    puts 'Syncing extraction data to Unblocked...'
+    puts "  Output dir:     #{output_dir}"
+    puts "  Collection:     #{config.unblocked_collection_id}"
+    puts "  Repo URL:       #{config.unblocked_repo_url}"
+    puts
+
+    exporter = Woods::Unblocked::Exporter.new(index_dir: output_dir)
+    stats = exporter.sync_all
+
+    puts
+    puts 'Sync complete!'
+    puts "  Documents synced:   #{stats[:synced]}"
+    puts "  Documents skipped:  #{stats[:skipped]}"
+
+    if stats[:errors].any?
+      puts "  Errors:             #{stats[:errors].size}"
+      stats[:errors].first(5).each { |e| puts "    - #{e}" }
+      puts "    ... and #{stats[:errors].size - 5} more" if stats[:errors].size > 5
+    end
+  end
+
+  desc 'Relay findings to Unblocked (alias for unblocked_sync)'
+  task relay: :unblocked_sync
 end

data/lib/woods/extractors/model_extractor.rb

@@ -327,6 +327,9 @@ module Woods
           callbacks: extract_callbacks(model),
           scopes: extract_scopes(model, source),
           enums: extract_enums(model),
+          inlined_concerns: extract_included_modules(model)
+                            .select { |mod| mod.name && concern_source(mod) }
+                            .map { |mod| mod.name.demodulize },
 
           # API surface
           class_methods: model.methods(false).sort,
@@ -611,7 +614,7 @@ module Woods
       def extract_dependencies(model, source = nil)
         # Associations point to other models
         deps = model.reflect_on_all_associations.filter_map do |assoc|
-          { type: :model, target: assoc.class_name, via: :association }
+          { type: :model, target: assoc.class_name, via: assoc.macro }
         rescue NameError => e
           @warnings << "[#{model.name}] Skipping broken association dep #{assoc.name}: #{e.message}"
           nil

data/lib/woods/graph_analyzer.rb

@@ -154,6 +154,52 @@ module Woods
         end
     end
 
+    # Group units into semantic domains using namespace prefixes and graph connectivity.
+    #
+    # Strategy:
+    # 1. Seed clusters from top-level namespace prefixes (e.g., ShippingProfile::*, Order::*)
+    # 2. Assign unnamespaced units to their most-connected cluster
+    # 3. Merge small clusters (< min_size) into their most-connected neighbor
+    # 4. For each cluster, identify the hub (highest PageRank) and entry points
+    # 5. Compute boundary edges between clusters
+    #
+    # @param min_size [Integer] Minimum units per cluster before merging (default: 3)
+    # @param types [Array<String>, nil] Filter to these unit types (default: all)
+    # @return [Array<Hash>] Clusters sorted by member count descending.
+    #   Each hash: { name:, hub:, members:, member_count:, entry_points:, boundary_edges:, types: }
+    def domain_clusters(min_size: 3, types: nil)
+      nodes = graph_nodes
+      return [] if nodes.empty?
+
+      # Filter by types if specified
+      filtered_ids = if types
+                       type_set = types.map(&:to_s)
+                       nodes.select { |_, meta| type_set.include?(meta[:type].to_s) }.keys
+                     else
+                       nodes.keys
+                     end
+
+      return [] if filtered_ids.empty?
+
+      # Step 1: Seed clusters from namespace prefixes
+      clusters = seed_namespace_clusters(filtered_ids, nodes)
+
+      # Step 2: Assign unnamespaced/root units to most-connected cluster
+      assign_orphaned_units(clusters, filtered_ids, nodes)
+
+      # Step 3: Merge small clusters
+      merge_small_clusters(clusters, min_size)
+
+      # Step 4: Enrich each cluster with hub, entry points, boundary edges
+      pagerank_scores = @graph.pagerank
+      enrich_clusters(clusters, nodes, pagerank_scores)
+
+      # Sort by member count descending
+      clusters.values
+              .select { |c| c[:members].any? }
+              .sort_by { |c| -c[:member_count] }
+    end
+
     # Full analysis report combining all structural metrics.
     #
     # @return [Hash] Complete analysis with :orphans, :dead_ends, :hubs,
@@ -182,6 +228,171 @@ module Woods
 
     private
 
+    # ──────────────────────────────────────────────────────────────────────
+    # Domain Cluster Helpers
+    # ──────────────────────────────────────────────────────────────────────
+
+    # Extract the top-level namespace prefix for clustering.
+    # "ShippingProfile::Setting" => "ShippingProfile"
+    # "Order::Transactions::Refund" => "Order"
+    # "Account" => nil (no namespace)
+    def cluster_prefix(identifier)
+      parts = identifier.to_s.split('::')
+      parts.size > 1 ? parts.first : nil
+    end
+
+    # Seed initial clusters from namespace prefixes.
+    def seed_namespace_clusters(filtered_ids, _nodes)
+      clusters = {}
+
+      filtered_ids.each do |id|
+        prefix = cluster_prefix(id)
+        next unless prefix
+
+        clusters[prefix] ||= { name: prefix, members: [], member_set: Set.new }
+        clusters[prefix][:members] << id
+        clusters[prefix][:member_set].add(id)
+      end
+
+      clusters
+    end
+
+    # Assign units with no namespace prefix to their most-connected cluster.
+    def assign_orphaned_units(clusters, filtered_ids, _nodes)
+      return if clusters.empty?
+
+      unassigned = filtered_ids.select { |id| cluster_prefix(id).nil? }
+
+      unassigned.each do |id|
+        best_cluster = find_most_connected_cluster(id, clusters)
+        next unless best_cluster
+
+        clusters[best_cluster][:members] << id
+        clusters[best_cluster][:member_set].add(id)
+      end
+    end
+
+    # Find which cluster a unit has the most connections to.
+    def find_most_connected_cluster(identifier, clusters)
+      connections = Hash.new(0)
+
+      # Check forward edges (dependencies)
+      @graph.dependencies_of(identifier).each do |dep|
+        clusters.each do |name, cluster|
+          connections[name] += 1 if cluster[:member_set].include?(dep)
+        end
+      end
+
+      # Check reverse edges (dependents)
+      @graph.dependents_of(identifier).each do |dep|
+        clusters.each do |name, cluster|
+          connections[name] += 1 if cluster[:member_set].include?(dep)
+        end
+      end
+
+      return nil if connections.empty?
+
+      connections.max_by { |_, count| count }.first
+    end
+
+    # Merge clusters smaller than min_size into their most-connected neighbor.
+    def merge_small_clusters(clusters, min_size)
+      loop do
+        small = clusters.select { |_, c| c[:members].size < min_size }
+        break if small.empty?
+
+        # Merge the smallest cluster first
+        name, cluster = small.min_by { |_, c| c[:members].size }
+
+        # Find which other cluster this one connects to most
+        target = find_merge_target(cluster, clusters, name)
+
+        if target
+          clusters[target][:members].concat(cluster[:members])
+          cluster[:members].each { |id| clusters[target][:member_set].add(id) }
+        end
+
+        clusters.delete(name)
+      end
+    end
+
+    # Find the best cluster to merge into (most cross-cluster edges).
+    def find_merge_target(cluster, all_clusters, exclude_name)
+      connections = Hash.new(0)
+
+      cluster[:members].each do |id|
+        (@graph.dependencies_of(id) + @graph.dependents_of(id)).each do |connected|
+          all_clusters.each do |name, other|
+            next if name == exclude_name
+
+            connections[name] += 1 if other[:member_set].include?(connected)
+          end
+        end
+      end
+
+      return nil if connections.empty?
+
+      connections.max_by { |_, count| count }.first
+    end
+
+    # Enrich clusters with hub, entry points, boundary edges, and type breakdown.
+    def enrich_clusters(clusters, nodes, pagerank_scores)
+      clusters.each_value do |cluster|
+        members = cluster[:members]
+        member_set = cluster[:member_set]
+
+        # Hub: highest PageRank within the cluster
+        hub_id = members.max_by { |id| pagerank_scores[id] || 0 }
+        cluster[:hub] = hub_id
+
+        # Entry points: controllers and GraphQL resolvers in the cluster's dependents
+        entry_types = %w[controller graphql_resolver graphql_mutation graphql_query]
+        entry_points = Set.new
+        members.each do |id|
+          @graph.dependents_of(id).each do |dep|
+            meta = nodes[dep]
+            entry_points.add(dep) if meta && entry_types.include?(meta[:type].to_s)
+          end
+        end
+        cluster[:entry_points] = entry_points.to_a
+
+        # Boundary edges: connections that cross cluster boundaries
+        boundary = []
+        members.each do |id|
+          @graph.dependencies_of(id).each do |dep|
+            next if member_set.include?(dep)
+
+            dep_meta = nodes[dep]
+            next unless dep_meta
+
+            boundary << { from: id, to: dep, via: 'dependency' }
+          end
+
+          @graph.dependents_of(id).each do |dep|
+            next if member_set.include?(dep)
+
+            dep_meta = nodes[dep]
+            next unless dep_meta
+
+            boundary << { from: dep, to: id, via: 'dependent' }
+          end
+        end
+        # Deduplicate and limit boundary edges
+        cluster[:boundary_edges] = boundary.uniq { |e| [e[:from], e[:to]] }.first(20)
+
+        # Type breakdown
+        type_counts = members.each_with_object(Hash.new(0)) do |id, counts|
+          meta = nodes[id]
+          counts[meta[:type].to_s] += 1 if meta
+        end
+        cluster[:types] = type_counts
+
+        # Final shape
+        cluster[:member_count] = members.size
+        cluster.delete(:member_set) # Internal tracking, not part of output
+      end
+    end
+
     # ──────────────────────────────────────────────────────────────────────
     # Graph Accessors
     # ──────────────────────────────────────────────────────────────────────

data/lib/woods/mcp/renderers/markdown_renderer.rb

@@ -165,6 +165,67 @@ module Woods
           lines.join("\n").rstrip
         end
 
+        # ── domain_clusters ────────────────────────────────────────
+
+        # @param data [Hash] Domain cluster data with :clusters and :total
+        # @return [String] Markdown domain cluster overview
+        def render_domain_clusters(data, **)
+          clusters = fetch_key(data, :clusters) || []
+          total = fetch_key(data, :total) || clusters.size
+          lines = []
+          lines << '## Domain Clusters'
+          lines << ''
+          lines << "#{total} domains detected."
+          lines << ''
+
+          clusters.each do |cluster|
+            name = cluster[:name] || cluster['name']
+            member_count = cluster[:member_count] || cluster['member_count'] || 0
+            hub = cluster[:hub] || cluster['hub']
+            lines << "### #{name} (#{member_count} units)"
+            lines << ''
+            lines << "**Hub:** #{hub}" if hub
+            lines << ''
+
+            # Type breakdown
+            types = cluster[:types] || cluster['types']
+            if types.is_a?(Hash) && types.any?
+              type_parts = types.sort_by { |_, count| -count }.map { |type, count| "#{count} #{type}s" }
+              lines << "**Types:** #{type_parts.join(', ')}"
+            end
+
+            # Entry points
+            entry_points = cluster[:entry_points] || cluster['entry_points'] || []
+            lines << "**Entry points:** #{entry_points.first(10).join(', ')}" if entry_points.any?
+
+            # Members (show first 15)
+            members = cluster[:members] || cluster['members'] || []
+            if members.any?
+              lines << ''
+              lines << '**Members:**'
+              members.first(15).each { |m| lines << "- #{m}" }
+              lines << "- _... and #{members.size - 15} more_" if members.size > 15
+            end
+
+            # Boundary edges (show first 10)
+            boundaries = cluster[:boundary_edges] || cluster['boundary_edges'] || []
+            if boundaries.any?
+              lines << ''
+              lines << '**Boundary connections:**'
+              boundaries.first(10).each do |edge|
+                from = edge[:from] || edge['from']
+                to = edge[:to] || edge['to']
+                via = edge[:via] || edge['via']
+                lines << "- #{from} → #{to} (#{via})"
+              end
+            end
+
+            lines << ''
+          end
+
+          lines.join("\n").rstrip
+        end
+
         # ── pagerank ────────────────────────────────────────────────
 
         # @param data [Hash] PageRank data with :total_nodes and :results