improve image

README.md

@@ -1,16 +1,17 @@
-# kongruity: Signal from noise
+# kongruity: Signal from noise - 2025-2026 @sjDev - LICENSE: MIT
 
-“...All those moments will be lost in time, like tears in rain.”
+![kongruity demo image.](kongruity_with_frame.jpg)
 
-kongruity pulls in unstructured artifacts of the creative-engineering process -- to-dos, action items, agile tickets, Jira thread comments, Slack thread comments, retrospective notes -- and synthesizes them into semantically coherent, prioritized clusters that can be incorporated into implementation planning.
+kongruity pulls in unstructured artifacts of the creative-engineering process, capturing "AHA!" moments scattered across an engineering team's disparate tools: action items or backlog in Atlassian/Jira, user story comments, Slack discussions, retrospective feedback.
 
-In kongruity, the artifacts become "sticky notes." A board full of them looks chaotic.
 
-With a click, they are semantically evaluated, grouped into thematic clusters with descriptive headers, rankable and exportable to project planning and execution tools.
+It stores and synthesizes these into semantically coherent, prioritized clusters that can be incorporated into implementation planning.
 
-## Voyage AI voyage-3.5
 
-![Embedding model benchmarking.](Voyage.jpg)
+In kongruity, artifacts become "sticky notes." A board full looks chaotic. With a click, a RAG-pipeline levearges Models trained to semantically evaluate, group, cluster and add descriptive cluster headers.  
+
+
+These are rankable, editable and exportable to sprint project planning tools. 
 
 ## Clustering and evaluation: methodology
 
@@ -26,6 +27,10 @@ This yields an empirical groundedness evaluation. One model proposes the groupin
 
 Note that: before scoring, structural validation confirms that each note landed in exactly one cluster, that no cluster is empty, and that no hallucinated note IDs appear. A malformed response to the validation completely fails, rather than quietly returning a partial board.
 
+## Voyage AI voyage-3.5: best-in-class embedding
+
+![Embedding model benchmarking.](Voyage.jpg)
+
 ## Reading the cohesion score
 
 Average silhouette width is a widely-used measure of clustering quality. Higher values indicate:

ROADMAP.md

@@ -1,98 +0,0 @@
-# Roadmap: integration infrastructure
-
-Phase 2 output. Deconstructs [ARCHITECTURE.md](ARCHITECTURE.md) into ordered milestones with explicit contracts. Every path is relative to `backend/`.
-
-## Milestone dependency order
-
-```mermaid
-flowchart LR
-  M0["M0 TypeScript migration (done)"] --> M1["M1 Write path"]
-  M1 --> M2["M2 Inbound"]
-  M1 --> M3["M3 Identity"]
-  M2 --> M4["M4 Transform and deliver"]
-  M3 --> M4
-  M4 --> M5["M5 Verification"]
-```
-
-M2 and M3 both depend only on M1 and can run in parallel.
-
-## Data models
-
-### `integrations`
-
-| Column | Type | Notes |
-| --- | --- | --- |
-| `id` | `SERIAL PRIMARY KEY` | |
-| `provider` | `VARCHAR(32) NOT NULL` | registry slug, e.g. `slack`, `rest` |
-| `external_workspace_id` | `VARCHAR(128)` | provider's own workspace identifier |
-| `display_name` | `VARCHAR(255)` | for operator legibility |
-| `api_key_hash` | `CHAR(64)` | SHA-256 of the inbound key; null unless the integration accepts pushes |
-| `access_token_ciphertext` | `TEXT` | AES-256-GCM, `iv:tag:payload` base64 triple |
-| `refresh_token_ciphertext` | `TEXT` | same encoding |
-| `token_expires_at` | `TIMESTAMPTZ` | drives refresh-before-use |
-| `scopes` | `TEXT[]` | granted at install |
-| `signing_secret_ciphertext` | `TEXT` | per-install webhook secret where the provider issues one |
-| `created_at` / `updated_at` | `TIMESTAMPTZ DEFAULT NOW()` | |
-
-Unique on `(provider, external_workspace_id)`. Index on `api_key_hash`.
-
-### `ingest_events`
-
-| Column | Type | Notes |
-| --- | --- | --- |
-| `id` | `SERIAL PRIMARY KEY` | |
-| `provider` | `VARCHAR(32) NOT NULL` | |
-| `external_id` | `VARCHAR(255) NOT NULL` | provider's event or message identifier |
-| `integration_id` | `INTEGER REFERENCES integrations(id)` | nullable for unmatched deliveries |
-| `status` | `VARCHAR(16) NOT NULL DEFAULT 'pending'` | `pending`, `processing`, `done`, `failed` |
-| `attempts` | `INTEGER NOT NULL DEFAULT 0` | |
-| `last_error` | `TEXT` | |
-| `received_at` / `updated_at` | `TIMESTAMPTZ DEFAULT NOW()` | |
-
-Unique on `(provider, external_id)`. This constraint is the deduplication mechanism: a redelivery hits the conflict and is dropped.
-
-## M1 — Write path
-
-**Ticket 1.1 — `db/migrate.ts`.** Add both tables above to the existing `up` script, `CREATE TABLE IF NOT EXISTS` in keeping with current style. Verify with `npm run db:migrate` against a live database.
-
-**Ticket 1.2 — `middleware/apiKey.ts`.** Express middleware reading `Authorization: Bearer <key>`, hashing with SHA-256, looking up `integrations.api_key_hash`, comparing with `crypto.timingSafeEqual`, attaching the row to `req`. Responds 401 with `{ error: string }` on any failure and never distinguishes "no such key" from "wrong key" in the response.
-
-**Ticket 1.3 — `routes/ingest.routes.ts`.** `POST /v1/notes` accepting `{ notes: NoteInput[] }`. Body narrowed by a type predicate, not a schema library. Returns `201` with `{ inserted: number, notes: Note[] }`, `400` on malformed body, `401` from the middleware. Delegates to the existing `createNotes` in [backend/db/notes.dao.ts](backend/db/notes.dao.ts), which already batches under the Postgres bind-parameter ceiling.
-
-**Ticket 1.4 — `app.ts` wiring.** Mount the ingest router. Ordering does not matter yet; it becomes critical in M2.
-
-## M2 — Inbound
-
-**Ticket 2.1 — `db/ingest_events.dao.ts`.** `recordDelivery` performing `INSERT ... ON CONFLICT (provider, external_id) DO NOTHING RETURNING id`, returning null when the row already existed so the caller can drop the redelivery. Plus `markProcessing`, `markDone`, `markFailed`.
-
-**Ticket 2.2 — `lib/signatures.ts`.** `verifySignature(provider, rawBody, headers, secret)` returning a discriminated result rather than throwing. HMAC comparison via `crypto.timingSafeEqual` on equal-length buffers. Enforces a replay window, default 300 seconds.
-
-**Ticket 2.3 — `routes/webhooks.routes.ts`.** `POST /v1/webhooks/:provider`. Resolves the provider from the registry (404 on unknown), answers challenge requests, verifies the signature (401 on failure), records the delivery (200 and stop on duplicate), enqueues, then returns 200. Must respond within the tightest provider budget, which is Slack's three seconds.
-
-**Ticket 2.4 — `app.ts` ordering.** Mount `express.raw({ type: '*/*' })` with the webhook router *before* `app.use(express.json())`. This is the single most breakable line in the system and needs a regression test of its own.
-
-## M3 — Identity
-
-**Ticket 3.1 — `lib/crypto.ts`.** `encryptSecret` and `decryptSecret` over AES-256-GCM using `TOKEN_ENCRYPTION_KEY`, node:crypto only. Fails loudly at startup if the key is absent or not 32 bytes.
-
-**Ticket 3.2 — `db/integrations.dao.ts`.** CRUD returning decrypted secrets only through explicit accessors, so a careless `SELECT *` cannot leak plaintext. `findByApiKeyHash`, `findByProviderWorkspace`, `upsertInstall`, `updateTokens`.
-
-**Ticket 3.3 — `services/oauth.service.ts`.** `buildAuthorizeUrl`, `exchangeCode`, `getValidAccessToken` refreshing when `token_expires_at` is inside a 60-second margin. Provider-specific endpoints come from the registry, not from this file.
-
-**Ticket 3.4 — `config/providers.ts`.** The registry. Each entry declares slug, signature scheme, header names, normalizer, OAuth endpoints, and scopes. Adding a provider must touch only this file plus one normalizer.
-
-## M4 — Transform and deliver
-
-**Ticket 4.1 — `services/normalize.service.ts`.** `normalize(provider, payload): NormalizedDelivery` returning `{ externalId: string, notes: NoteInput[] }`. Writes provenance into `source_meta`: provider, external id, permalink, author handle, received timestamp.
-
-**Ticket 4.2 — `lib/queue.ts`.** In-process FIFO with concurrency 1, exponential backoff, and a cap on attempts. On terminal failure calls `markFailed`. Exposes `enqueue`, `size`, and a `drain` promise for deterministic testing.
-
-**Ticket 4.3 — `lib/httpClient.ts`.** `requestJson` with timeout, retry on 429 and 5xx, `Retry-After` respected, jittered exponential backoff. Used by OAuth exchange today and export adapters later.
-
-## M5 — Verification
-
-End-to-end test driving a signed synthetic-provider delivery through the whole chain and asserting the note lands. Explicit cases: valid delivery inserts, replayed delivery is dropped, bad signature is rejected, unknown provider 404s, malformed REST body 400s, missing key 401s, and the raw-body ordering regression.
-
-## Definition of done per milestone
-
-`npm run type-check`, `npm run build`, and `npm test` all clean, with new unit tests for every module and no change in behavior to the four pre-existing suites.

agentic-orchestration.md

@@ -2,13 +2,11 @@
 
 You should assume the tole of  Lead Orchestrator Agent for a complex, long-horizon software development project.
 
-# The first rule. Hereinfter, the "King's Rule".
+# The first, inviolable rule.
 
-This is the King’s Rule: minimize token usage, but do not sacrifice quality.
+The Inviolable Rule: minimize token usage, but do not sacrifice quality.
 
-Strive for strict compliance to the King’s Rule.  
+Here is a non-exhaustive list of suggested strategies to achieve this:
-
-Here is a non-exhaustive list of suggested strategies pertaining to the King’s Rule.
 
 ### Sub-agents