Docs update + og image

Author: ofriw

astro.config.mjs

@@ -33,6 +33,52 @@ export default defineConfig({
           href: "https://github.com/chunkhound/chunkhound",
         },
       ],
+      head: [
+        // Open Graph
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image",
+            content: "https://chunkhound.github.io/og-image.png",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image:width",
+            content: "1200",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:image:height",
+            content: "630",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            property: "og:type",
+            content: "website",
+          },
+        },
+        // Twitter Card
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:card",
+            content: "summary_large_image",
+          },
+        },
+        {
+          tag: "meta",
+          attrs: {
+            name: "twitter:image",
+            content: "https://chunkhound.github.io/og-image.png",
+          },
+        },
+      ],
       sidebar: [
         { label: "Quickstart", slug: "quickstart" },
         { label: "How-To Guides", slug: "how-to" },

public/og-image.png

@@ -326,7 +326,13 @@ This implements a classic **precision-recall tradeoff**—cast a wide net during
 
 ### Map-Reduce Synthesis with Clustering
 
-When filtered results exceed single-LLM context limits (>150k tokens for large repositories), the system uses **token-bounded K-means clustering** to prevent context collapse. Files are partitioned into clusters of max 30k tokens each, synthesized in parallel with cluster-local citations [1][2][3], then deterministically remapped to global numbers before the reduce phase combines summaries.
+When semantic clustering produces multiple clusters from filtered results, the system uses **two-phase HDBSCAN clustering with map-reduce synthesis** to prevent context collapse:
+
+1. **Phase 1 (Natural Boundary Discovery)**: HDBSCAN (Hierarchical Density-Based Spatial Clustering) discovers natural semantic boundaries in the embedding space, grouping files where they are cohesively related rather than forcing arbitrary partitions. This respects the inherent structure of your codebase, identifying both semantically dense clusters and outliers that don't fit natural groupings.
+
+2. **Phase 2 (Token-Budget Grouping)**: Clusters are greedily merged based on centroid distance while respecting the 30k token limit per cluster, preserving semantic coherence during merging.
+
+Files are partitioned into token-bounded clusters, synthesized in parallel with cluster-local citations [1][2][3], then deterministically remapped to global numbers before the reduce phase combines summaries.
 
 This avoids **progressive compression loss** from iterative summarization chains (summary → summary-of-summary). Each cluster synthesizes once with full context, preserving architectural details while enabling arbitrary scaling. Cluster-local citation namespaces enable maximum parallelism—no coordination needed during map phase. The reduce LLM integrates remapped summaries with explicit instructions to preserve citations (not generate new ones), ensuring every [N] traces to actual source files.