add agents.md

Reviewed-on: #5

README.md

@@ -1,4 +1,4 @@
-# kongruity
+# kongruity: Signal from noise
 
 “...All those moments will be lost in time, like tears in rain.”
 
@@ -8,15 +8,19 @@ In kongruity, the artifacts become "sticky notes." A board full of them looks ch
 
 With a click, they are semantically evaluated, grouped into thematic clusters with descriptive headers, rankable and exportable to project planning and execution tools.
 
+## Voyage AI voyage-3.5
+
+![Embedding model benchmarking.](Voyage.jpg)
+
 ## Clustering and evaluation: methodology
 
 Two models run in parallel, and neither sees the other's work. Anthropic's `claude-sonnet-5` (`backend/services/clustering.service.js`) reads the raw text of every note and groups them into labeled thematic clusters. 
 
-At the same time, Voyage AI's voyage-3 model (`backend/services/embedding.service.js`) converts each note's text into a numeric representation of its semantic meaning aka vector. 
+At the same time, Voyage AI's voyage-3.5 model (`backend/services/embedding.service.js`) converts each note's text into a numeric representation of its semantic meaning aka vector. 
 
-Once the LLM returns, kongruity scores that grouping (`backend/services/validation.service.js`) using an established silhouette coefficient, with cosine distance rather than Euclidean as the distance metric. 
+Once the LLM returns, kongruity scores that grouping (`backend/services/validation.service.js`) using an established silhouette coefficient, with cosine distance rather than Euclidean as the proximity metric. 
 
-For each note, it weighs the average distance to the other notes in its own cluster against the average distance to the notes in the nearest neighboring cluster. Averaged across every note, this yields a single cohesion score in the range [−1, 1], displayed at the top of the results.
+For each note, it weighs the average distance to the other notes in its own cluster against the average distance to the notes in the nearest neighboring cluster. Averaged across every note, this yields a single numeric cohesion score, displayed at the top of the results, along with plaintext: Strong, Moderate, Weak, Poor.
 
 This yields an empirical groundedness evaluation. One model proposes the grouping; an independent model evaluates grouping accuracy.
 
@@ -30,14 +34,18 @@ Average silhouette width is a widely-used measure of clustering quality. Higher
 
 2. How well-separated each cluster is from its nearest neighboring cluster.
 
+Although the coefficient is mathematically bounded by [−1, 1], cosine distance between high-dimensional text embeddings is compressed: unrelated notes sit close to orthogonal, so both the within-cluster and nearest-cluster distances land near 0.8. Because silhouette divides the gap between them by the larger of the two, the practical range on embedding data is roughly [−0.05, 0.10] rather than the full interval.
+
+The bands below are therefore calibrated against that observed range. On the seed board, the five ideal thematic clusters score 0.09; swapping a few notes between clusters drops it to 0.06; a scrambled assignment falls below zero.
+
 The score appears above the results with a plain-language band:
 
-- **0.70 and above** — Strong
-- **0.40 to 0.69** — Moderate
-- **0.10 to 0.39** — Weak
-- **Below 0.10** — Poor
+- **0.07 and above** — Strong
+- **0.04 to 0.06** — Moderate
+- **0.01 to 0.03** — Weak
+- **Below 0.01** — Poor
 
-Silhouette values are archetypically bounded below 1.0 for real-world data, so the number is best read as a relative measure. See Hugo Sträng, Tai Dinh. An upper bound on the silhouette evaluation metric for clustering. Pattern Recognition, Volume 178, 2026, 113402, ISSN 0031-3203.
+A score near 0.00 means the grouping is no better than chance. Bands are specific to `voyage-3` cosine distance and would need recalibration behind a different embedding model. See Hugo Sträng, Tai Dinh. An upper bound on the silhouette evaluation metric for clustering. Pattern Recognition, Volume 178, 2026, 113402, ISSN 0031-3203.
 
 ## Organizing clusters, exporting to workflow software
 

agents.md

@@ -0,0 +1,42 @@
+# AI Agent Instructions: Fullstack Vite 7 (React) + Express + TypeScript + npm
+
+You are an expert AI fullstack software engineer specialized in Vite 7, React, Express, TypeScript, and modern web architectures. Follow these rules strictly when modifying this codebase.
+
+## 1. Project Structure & Context
+* **Frontend:** React SPA powered by Vite 7.x (Entry: `src/main.tsx` or client folder).
+* **Backend:** Express Node.js application (Server entry: `server.ts` or server folder).
+* **Package Manager:** npm (`package-lock.json` is the strict source of truth).
+* **TypeScript Setup:** Strict Mode enabled independently across both environments.
+
+## 2. Express Backend TypeScript Rules
+* **Typed Request/Response:** Explicitly type Express route handlers using native Express types:
+  ```typescript
+  import { Request, Response, NextFunction } from 'express';
+  // Example for typed request bodies/params:
+  interface CreateUserBody { username: string; }
+  app.post('/user', (req: Request<{}, {}, CreateUserBody>, res: Response) => { ... });
+  ```
+* **Async Error Catching:** Always wrap async middleware/route handlers in `try/catch` and pass errors to `next(err)`. Do not let unhandled promise rejections crash the Node process.
+* **Shared Types:** If frontend and backend share types (e.g., API payloads, User models), place them in a shared directory or export them cleanly from the backend to prevent duplicating code.
+
+## 3. Frontend React + Vite Rules
+* **Component Typings:** Use standard type inference or explicit return types (`function Component(): React.JSX.Element`). Avoid the legacy `React.FC`.
+* **Strict Prop Types:** Every component must have an explicitly typed `interface` or `type` for its props. No implicit `any`.
+* **Event Handlers:** Use exact React synthetic event types (e.g., `React.ChangeEvent<HTMLInputElement>`) instead of generic native events.
+* **File Extensions:** Use `.tsx` exclusively for files containing JSX. Use `.ts` strictly for pure logic, hooks, or type definitions.
+
+## 4. Strict Code Quality & Native Guards
+* **No `any`:** Never use `any`. Use `unknown` for unpredictable runtime data (like Express `req.body` or frontend `fetch` payloads).
+* **No Validation Libraries:** Do not install Zod, TypeBox, or Yup. Write explicit, manual type predicate functions (`function isUser(obj: any): obj is User`) to safely validate runtime data incoming to both the server and client.
+* **No Enums:** Avoid TypeScript `enum`. Use string-literal unions (`type Status = 'active' | 'pending'`) or `const StatusEnum = { ... } as const`.
+
+## 5. Verification & Workflow Commands
+Before declaring a task complete, you must verify both environments compile flawlessly via npm:
+* **Install Dependencies:** `npm install`
+* **Type-Check Project:** Run the designated workspace or folder type-checking scripts (e.g., `npm run type-check` or `npx tsc --noEmit` across both roots).
+* **Build Verification:** Run production build scripts (e.g., `npm run build`) to ensure both Express asset compilation and Vite bundling pass without error.
+
+## 6. How to Respond
+* **Verify Types First:** Run type-checking commands automatically after modifying files to capture compilation breaks before presenting the solution.
+* **Targeted Diffs:** Provide concise, targeted updates. Do not rewrite whole files if only a few lines change.
+* **Self-Correct:** If a build command fails, read the compiler/Vite/Node logs, fix the root cause, and re-test before asking the user for help.

backend/services/embedding.service.js

@@ -27,7 +27,7 @@ export const embedNotes = async (notes) => {
             for await (const chunk of batches) {
                 const response = await client.embed({
                     input: chunk.map((n) => n.text),
-                    model: "voyage-3",
+                    model: "voyage-3.5",
                 });
 
                 response.data.forEach((item, i) => {

frontend/package.json

@@ -1,40 +1,39 @@
 {
-   "name": "congruity-frontend",
-   "private": true,
-   "version": "0.1.0",
-   "type": "module",
-   "scripts": {
-     "dev": "vite",
-     "build": "tsc -b && vite build",
-     "lint": "eslint .",
-     "preview": "vite preview",
-     "test": "vitest run --config vitest.config.ts",
-     "test:watch": "vitest --config vitest.config.ts"
-   },
-   "dependencies": {
-     "@tanstack/react-query": "^5.90.21",
-     "react": "^19.2.0",
-     "react-dom": "^19.2.0",
-     "react-router-dom": "^7.13.0"
-   },
-   "devDependencies": {
-     "@eslint/js": "^9.39.1",
-     "@testing-library/jest-dom": "^6.9.1",
-     "@testing-library/react": "^16.3.2",
-     "@testing-library/user-event": "^14.6.1",
-     "@types/node": "^24.10.1",
-     "@types/react": "^19.2.7",
-     "@types/react-dom": "^19.2.3",
-     "@vitejs/plugin-react": "^5.1.1",
-     "eslint": "^9.39.1",
-     "eslint-plugin-react-hooks": "^7.0.1",
-     "eslint-plugin-react-refresh": "^0.4.24",
-     "globals": "^16.5.0",
-     "jsdom": "^28.0.0",
-     "typescript": "~5.9.3",
-     "typescript-eslint": "^8.48.0",
-     "vite": "^7.3.1",
-     "vitest": "^4.0.18"
-   }
- }
- 
+    "name": "kongruity-frontend",
+    "private": true,
+    "version": "0.1.0",
+    "type": "module",
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc -b && vite build",
+        "lint": "eslint .",
+        "preview": "vite preview",
+        "test": "vitest run --config vitest.config.ts",
+        "test:watch": "vitest --config vitest.config.ts"
+    },
+    "dependencies": {
+        "@tanstack/react-query": "^5.90.21",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
+        "react-router-dom": "^7.13.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.39.1",
+        "@testing-library/jest-dom": "^6.9.1",
+        "@testing-library/react": "^16.3.2",
+        "@testing-library/user-event": "^14.6.1",
+        "@types/node": "^24.10.1",
+        "@types/react": "^19.2.7",
+        "@types/react-dom": "^19.2.3",
+        "@vitejs/plugin-react": "^5.1.1",
+        "eslint": "^9.39.1",
+        "eslint-plugin-react-hooks": "^7.0.1",
+        "eslint-plugin-react-refresh": "^0.4.24",
+        "globals": "^16.5.0",
+        "jsdom": "^28.0.0",
+        "typescript": "~5.9.3",
+        "typescript-eslint": "^8.48.0",
+        "vite": "^7.3.1",
+        "vitest": "^4.0.18"
+    }
+}

frontend/src/components/stickies.tsx

@@ -6,132 +6,136 @@ import Sticky from './sticky';
 import Button from './button';
 import '../styles/stickies.css';
 
+// In practice, silhouette on cosine distance between text embeddings occupies roughly
+// [-0.05, 0.10], not strict theoretical [-1, 1]: near-orthogonal vectors put both the within- and
+// nearest-cluster distances close to 0.8, and the coefficient divides their gap
+// by the larger. These bands are calibrated to that range for voyage-3. see README, Reading the cohesion score
 const scoreLabel = (score: number): string => {
-  if (score >= 0.7) return 'Strong';
-  if (score >= 0.4) return 'Moderate';
-  if (score >= 0.1) return 'Weak';
-  return 'Poor';
+    if (score >= 0.07) return 'Strong';
+    if (score >= 0.04) return 'Moderate';
+    if (score >= 0.01) return 'Weak';
+    return 'Poor';
 };
 
 const Stickies = () => {
-  const { data: stickies, isLoading, error } = useGetStickies();
-  const { mutate: cluster, data: clusterResponse, isPending } = useClusterStickies();
+    const { data: stickies, isLoading, error } = useGetStickies();
+    const { mutate: cluster, data: clusterResponse, isPending } = useClusterStickies();
 
-  const [rankedClusters, setRankedClusters] = useState<RankedCluster[]>([]);
-  const dragIndex = useRef<number | null>(null);
-  const [dragOverIndex, setDragOverIndex] = useState<number | null>(null);
+    const [rankedClusters, setRankedClusters] = useState<RankedCluster[]>([]);
+    const dragIndex = useRef<number | null>(null);
+    const [dragOverIndex, setDragOverIndex] = useState<number | null>(null);
 
-  useEffect(() => {
-    if (clusterResponse?.clusters) {
-      setRankedClusters(
-        clusterResponse.clusters.map((c, i) => ({ ...c, rank: i + 1 }))
-      );
-    }
-  }, [clusterResponse]);
+    useEffect(() => {
+        if (clusterResponse?.clusters) {
+            setRankedClusters(
+                clusterResponse.clusters.map((c, i) => ({ ...c, rank: i + 1 }))
+            );
+        }
+    }, [clusterResponse]);
 
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+    if (isLoading) return <div>Loading...</div>;
+    if (error) return <div>Error: {error.message}</div>;
 
-  const score = clusterResponse?.score;
+    const score = clusterResponse?.score;
 
-  const handleCluster = () => {
-    cluster();
-  };
+    const handleCluster = () => {
+        cluster();
+    };
 
-  const buildStickyMap = (): Map<string, StickyType> => {
-    const map = new Map<string, StickyType>();
-    stickies?.forEach((s) => map.set(s.id, s));
-    return map;
-  };
+    const buildStickyMap = (): Map<string, StickyType> => {
+        const map = new Map<string, StickyType>();
+        stickies?.forEach((s) => map.set(s.id, s));
+        return map;
+    };
 
-  const stickyMap = buildStickyMap();
+    const stickyMap = buildStickyMap();
 
-  const renderStickies = (items: StickyType[]) =>
-    items?.map((sticky) => <Sticky key={sticky.id} sticky={sticky} />);
+    const renderStickies = (items: StickyType[]) =>
+        items?.map((sticky) => <Sticky key={sticky.id} sticky={sticky} />);
 
-  const handleDragStart = (index: number) => {
-    dragIndex.current = index;
-  };
+    const handleDragStart = (index: number) => {
+        dragIndex.current = index;
+    };
 
-  const handleDragOver = (e: DragEvent, index: number) => {
-    e.preventDefault();
-    setDragOverIndex(index);
-  };
+    const handleDragOver = (e: DragEvent, index: number) => {
+        e.preventDefault();
+        setDragOverIndex(index);
+    };
 
-  const handleDragLeave = () => {
-    setDragOverIndex(null);
-  };
+    const handleDragLeave = () => {
+        setDragOverIndex(null);
+    };
 
-  const handleDrop = (targetIndex: number) => {
-    const sourceIndex = dragIndex.current;
-    if (sourceIndex === null || sourceIndex === targetIndex) {
-      dragIndex.current = null;
-      setDragOverIndex(null);
-      return;
-    }
+    const handleDrop = (targetIndex: number) => {
+        const sourceIndex = dragIndex.current;
+        if (sourceIndex === null || sourceIndex === targetIndex) {
+            dragIndex.current = null;
+            setDragOverIndex(null);
+            return;
+        }
 
-    const reordered = [...rankedClusters];
-    const [moved] = reordered.splice(sourceIndex, 1);
-    reordered.splice(targetIndex, 0, moved);
+        const reordered = [...rankedClusters];
+        const [moved] = reordered.splice(sourceIndex, 1);
+        reordered.splice(targetIndex, 0, moved);
 
-    setRankedClusters(reordered.map((c, i) => ({ ...c, rank: i + 1 })));
-    dragIndex.current = null;
-    setDragOverIndex(null);
-  };
+        setRankedClusters(reordered.map((c, i) => ({ ...c, rank: i + 1 })));
+        dragIndex.current = null;
+        setDragOverIndex(null);
+    };
 
-  const handleDragEnd = () => {
-    dragIndex.current = null;
-    setDragOverIndex(null);
-  };
-
-  return (
-    <div className="stickies-container">
-      <Button onClick={handleCluster} isLoading={isPending} label="Group Stickies By Topic" />
-      {rankedClusters.length > 0 ? (
-        <div className="clusters-container">
-          {score != null && (
-            <div className="cohesion-score">
-              Cluster cohesion: <strong>{score.toFixed(2)}</strong> — {scoreLabel(score)}
-            </div>
-          )}
-          {rankedClusters.map((group, index) => (
-            <div
-              key={group.label}
-              className={`cluster-group cluster-draggable${dragOverIndex === index ? ' cluster-drag-over' : ''}`}
-              draggable
-              onDragStart={() => handleDragStart(index)}
-              onDragOver={(e) => handleDragOver(e, index)}
-              onDragLeave={handleDragLeave}
-              onDrop={() => handleDrop(index)}
-              onDragEnd={handleDragEnd}
-            >
-              <div className="cluster-header">
-                <span className="cluster-rank" aria-label={`Priority ${group.rank}`}>
-                  {group.rank}
-                </span>
-                {group.rank === 1 && (
-                  <span className="cluster-reorder-hint">Drag and drop to reorganize cluster priority</span>
-                )}
-                <h3 className="cluster-label">{group.label}</h3>
-                <span className="cluster-drag-handle" aria-hidden="true">⠿</span>
-              </div>
-              <div className="stickies-grid">
-                {renderStickies(
-                  group?.noteIds
-                    .map((id) => stickyMap?.get(id))
-                    .filter((s): s is StickyType => !!s)
-                )}
-              </div>
-            </div>
-          ))}
+    const handleDragEnd = () => {
+        dragIndex.current = null;
+        setDragOverIndex(null);
+    };
+    console.log(score?.toFixed(2))
+    return (
+        <div className="stickies-container">
+            <Button onClick={handleCluster} isLoading={isPending} label="Group Stickies By Topic" />
+            {rankedClusters.length > 0 ? (
+                <div className="clusters-container">
+                    {score != null && (
+                        <div className="cohesion-score">
+                            Cluster cohesion: <strong>{scoreLabel(score)}</strong>
+                        </div>
+                    )}
+                    {rankedClusters.map((group, index) => (
+                        <div
+                            key={group.label}
+                            className={`cluster-group cluster-draggable${dragOverIndex === index ? ' cluster-drag-over' : ''}`}
+                            draggable
+                            onDragStart={() => handleDragStart(index)}
+                            onDragOver={(e) => handleDragOver(e, index)}
+                            onDragLeave={handleDragLeave}
+                            onDrop={() => handleDrop(index)}
+                            onDragEnd={handleDragEnd}
+                        >
+                            <div className="cluster-header">
+                                <span className="cluster-rank" aria-label={`Priority ${group.rank}`}>
+                                    {group.rank}
+                                </span>
+                                {group.rank === 1 && (
+                                    <span className="cluster-reorder-hint">Drag and drop to reorganize cluster priority</span>
+                                )}
+                                <h3 className="cluster-label">{group.label}</h3>
+                                <span className="cluster-drag-handle" aria-hidden="true">⠿</span>
+                            </div>
+                            <div className="stickies-grid">
+                                {renderStickies(
+                                    group?.noteIds
+                                        .map((id) => stickyMap?.get(id))
+                                        .filter((s): s is StickyType => !!s)
+                                )}
+                            </div>
+                        </div>
+                    ))}
+                </div>
+            ) : (
+                <div className="stickies-grid">
+                    {renderStickies(stickies ?? [])}
+                </div>
+            )}
         </div>
-      ) : (
-        <div className="stickies-grid">
-          {renderStickies(stickies ?? [])}
-        </div>
-      )}
-    </div>
-  );
+    );
 };
 
 export default Stickies;

frontend/src/styles/stickies.css

@@ -1,100 +1,107 @@
 .stickies-grid {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 16px;
-  justify-content: center;
-  margin-top: 18px;
-  padding: 24px;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 16px;
+    justify-content: center;
+    margin-top: 18px;
+    padding: 24px;
 }
 
 .stickies-container {
-  margin: 36px 0px 36px 0px;
+    margin: 36px 0px 36px 0px;
 }
 
 .clusters-container {
-  display: flex;
-  flex-direction: column;
-  gap: 32px;
-  padding: 24px 0;
+    display: flex;
+    flex-direction: column;
+    gap: 32px;
+    padding: 24px 0;
 }
 
 .cluster-group {
-  border: 1px solid #6dd6f4;
-  border-radius: 8px;
-  padding: 16px;
+    border: 1px solid #6dd6f4;
+    border-radius: 8px;
+    padding: 16px;
 }
 
 .cluster-draggable {
-  cursor: grab;
-  transition: box-shadow 0.2s ease, border-color 0.2s ease, transform 0.15s ease;
+    cursor: grab;
+    transition: box-shadow 0.2s ease, border-color 0.2s ease, transform 0.15s ease;
 }
 
 .cluster-draggable:active {
-  cursor: grabbing;
+    cursor: grabbing;
 }
 
 .cluster-drag-over {
-  border-color: #ffb7ce;
-  box-shadow: 0 0 12px rgba(255, 183, 206, 0.4);
-  transform: scale(1.01);
+    border-color: #ffb7ce;
+    box-shadow: 0 0 12px rgba(255, 183, 206, 0.4);
+    transform: scale(1.01);
 }
 
 .cluster-header {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  margin-bottom: 16px;
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 16px;
+    min-height: 32px;
 }
 
 .cluster-rank {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 32px;
-  height: 32px;
-  border-radius: 50%;
-  background: #6dd6f4;
-  color: #1a1a2e;
-  font-weight: 700;
-  font-size: 0.95em;
-  flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    border-radius: 50%;
+    background: #6dd6f4;
+    color: #1a1a2e;
+    font-weight: 700;
+    font-size: 0.95em;
+    flex-shrink: 0;
 }
 
 .cluster-reorder-hint {
-  font-size: 0.8em;
-  color: #9ca3af;
-  font-style: italic;
-  white-space: nowrap;
-  flex-shrink: 0;
+    font-size: 0.8em;
+    color: #9ca3af;
+    font-style: italic;
+    white-space: nowrap;
+    flex-shrink: 0;
 }
 
 .cluster-label {
-  margin: 0;
-  font-size: 1.2em;
-  font-weight: 600;
-  flex: 1;
+    position: absolute;
+    left: 50%;
+    transform: translateX(-50%);
+    max-width: 50%;
+    margin: 0;
+    font-size: 1.2em;
+    font-weight: 600;
+    pointer-events: none;
 }
 
 .cluster-drag-handle {
-  font-size: 1.4em;
-  color: #6dd6f4;
-  opacity: 0.4;
-  user-select: none;
-  transition: opacity 0.2s ease;
-  flex-shrink: 0;
+    margin-left: auto;
+    font-size: 1.4em;
+    color: #6dd6f4;
+    opacity: 0.4;
+    user-select: none;
+    transition: opacity 0.2s ease;
+    flex-shrink: 0;
 }
 
 .cluster-draggable:hover .cluster-drag-handle {
-  opacity: 0.8;
+    opacity: 0.8;
 }
 
 .cohesion-score {
-  text-align: center;
-  font-size: 0.95em;
-  color: #e0e0e0;
-  padding: 8px 16px;
-  background: rgba(109, 214, 244, 0.1);
-  border-radius: 6px;
-  width: fit-content;
-  margin: 0 auto;
+    text-align: center;
+    font-size: 0.95em;
+    color: #e0e0e0;
+    padding: 8px 16px;
+    background: rgba(109, 214, 244, 0.1);
+    border-radius: 6px;
+    width: fit-content;
+    margin: 0 auto;
 }

frontend/src/tests/stickies.test.tsx

@@ -14,7 +14,7 @@ const MOCK_CLUSTER_RESPONSE = {
     { label: 'Auth Issues', noteIds: ['note_001'] },
     { label: 'Export Issues', noteIds: ['note_002'] },
   ],
-  score: 0.74,
+  score: 0.09,
 };
 
 let fetchMock: ReturnType<typeof vi.fn>;