feat(ai): evidence ledger and Impressum-first lead research (#3)

The agent's only research tool was a single GET with a few regexes, and
whatever it produced went straight into the lead with no record of where
it came from — including over a value the operator had typed. This gives
it eyes and a memory of what it saw.

Evidence ledger (api/src/facts.ts, new `lead_facts` table)

Every machine-written value is now an observation carrying its source,
what the source literally said, and a grade. Only a claim the business
makes about itself fills an empty field; anything weaker, and anything
disagreeing with a hand-set value, becomes a suggestion a human accepts
or rejects. Provenance is derived rather than stored: a lead value counts
as machine-set only while it still matches an applied fact, so imports
and manual edits are untouchable. Fields the leads table has no column
for (USt-IdNr., Handelsregister, Rechtsform, Geschäftsführung) live in
the ledger and are there when the lead becomes a Kunde.

Impressum-first research (api/src/ai/research.ts)

Replaces fetch_website. Walks homepage -> Impressum and returns
observations with source URLs. §5 DDG obliges every German business site
to publish exactly the fields we want, which makes it a free primary
source. probeTech now measures mobile_friendly, tech and
staleness_signal off the markup instead of letting the model imagine
them. The SSRF guard is shared and now also covers redirect targets.

Built for the local model: create_lead({ research: true, analyze: true })
does the whole URL-to-qualified-lead path in one call, research_company
records what it observed itself rather than making a small model chain
six record_fact calls, params are flat and enum-constrained, and every
response explains why it did what it did.

MCP reaches all of it — research_company, list_lead_facts, review_facts
in the read tier; research_lead, record_fact, resolve_fact in the
reversible-write tier — over new routes under /api/ai and /api/leads.

Two bugs fixed on the way:

- analyzeLead overwrote a priority a human set by dragging a card, on
  every re-run. It now only revises a priority it set itself. score is
  left alone since it is the model's own fit metric and the importer
  seeds it.
- decode() handled no German named entities, so `Müller` would have
  been filed as a Firmenname.

UI: a Recherche & Herkunft panel in the lead drawer with the review queue
and a provenance trail.

vite.config.ts takes an API_URL override so the dev server can point at
an API on another port; the default is unchanged.

195 api + 17 cli tests pass, including HTTP integration over the Bearer
token path MCP uses. Verified in a running instance: grading correct over
the wire, accept wrote through, reject left the field alone, unreachable
site degraded cleanly.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: lucas19919

api/package.json

@@ -9,7 +9,7 @@
     "import": "tsx scripts/import-xlsx.ts",
     "backup": "tsx scripts/backup.ts",
     "restore": "tsx scripts/restore.ts",
-    "test": "node --import tsx --test --test-concurrency=1 src/documents.test.ts src/pdf.test.ts src/validate.test.ts src/facturx.test.ts src/mailer.test.ts src/export.test.ts src/dsgvo.test.ts src/payments.test.ts src/expenses.test.ts src/subscriptions.test.ts src/backup.test.ts src/recurring.test.ts src/contracts.test.ts src/catalog.test.ts src/dashboard.test.ts src/customers.test.ts src/storno.test.ts src/report.test.ts src/leads.test.ts src/leadIntel.test.ts src/ai-leadtools.test.ts src/ai-newtools.test.ts src/tokens.test.ts src/machine.test.ts"
+    "test": "node --import tsx --test --test-concurrency=1 src/documents.test.ts src/pdf.test.ts src/validate.test.ts src/facturx.test.ts src/mailer.test.ts src/export.test.ts src/dsgvo.test.ts src/payments.test.ts src/expenses.test.ts src/subscriptions.test.ts src/backup.test.ts src/recurring.test.ts src/contracts.test.ts src/catalog.test.ts src/dashboard.test.ts src/customers.test.ts src/storno.test.ts src/report.test.ts src/leads.test.ts src/leadIntel.test.ts src/facts.test.ts src/research.test.ts src/facts-routes.test.ts src/ai-leadtools.test.ts src/ai-newtools.test.ts src/tokens.test.ts src/machine.test.ts"
   },
   "dependencies": {
     "@hono/node-server": "^1.13.7",

api/src/ai/leadIntel.ts

@@ -2,6 +2,7 @@ import { db, type LeadRow, type LeadAiRow, type OutreachRow } from '../db'
 import { getSettings } from '../documents'
 import { audit } from '../audit'
 import { chatJSON, AI } from './provider'
+import { ledgerOnlyFacts } from '../facts'
 import { LEAD_ANALYST_SYSTEM, OUTREACH_SYSTEM, INVOICE_DRAFTER_SYSTEM } from './prompts'
 
 function leadFacts(lead: LeadRow): string {
@@ -20,6 +21,11 @@ function leadFacts(lead: LeadRow): string {
     stage: lead.stage,
     notizen: lead.notes,
   }
+  // Impressum-derived facts the leads table has no column for. They sharpen the
+  // read considerably: knowing the Rechtsform and who signs tells the analyst
+  // whether this is a one-person Betrieb or something with a Geschäftsführung.
+  const extra = ledgerOnlyFacts(lead.id)
+  if (Object.keys(extra).length) f.impressum = extra
   return JSON.stringify(f, null, 2)
 }
 
@@ -41,8 +47,29 @@ const QUALIFICATION_PRIORITY: Record<string, string> = {
   disqualified: 'niedrig',
 }
 
+/**
+ * May the analysis still set `priority`, or has the operator taken it over?
+ * Priority is the one ranking a human sets deliberately — by dragging a card —
+ * so re-running the analysis must not quietly undo that. Derived the same way
+ * the evidence ledger derives provenance: the value counts as machine-set while
+ * it still matches what the machine last wrote, or sits untouched at its default.
+ *
+ * `score` deliberately gets no such protection: it is the model's own 0..100 fit
+ * confidence (and the importer's staleness heuristic before that), not something
+ * anyone curates by hand.
+ */
+function priorityIsMachineOwned(lead: LeadRow): boolean {
+  if (lead.priority === 'mittel') return true // untouched default
+  const prev = db.prepare('SELECT qualification FROM lead_ai WHERE lead_id = ?').get(lead.id) as
+    | { qualification: string | null }
+    | undefined
+  const lastPriority = prev?.qualification ? QUALIFICATION_PRIORITY[prev.qualification] : undefined
+  return !!lastPriority && lead.priority === lastPriority
+}
+
 /** Run (or re-run) the AI assessment for a lead and cache it. */
 export async function analyzeLead(lead: LeadRow, actor: string): Promise<LeadAiRow> {
+  const maySetPriority = priorityIsMachineOwned(lead)
   const a = await chatJSON<LeadAnalysis>(
     LEAD_ANALYST_SYSTEM,
     `Bewerte diesen Lead:\n\n${leadFacts(lead)}`,
@@ -73,10 +100,11 @@ export async function analyzeLead(lead: LeadRow, actor: string): Promise<LeadAiR
   // Let the AI assessment steer the pipeline board: the qualification sets the
   // priority (urgency) and the model's fit confidence (0..100) becomes the lead
   // score used to rank leads — so a freshly analysed lead no longer sits at 0.
+  // ...but only where a human has not already made that call themselves.
   const mapped = a.qualification ? QUALIFICATION_PRIORITY[a.qualification] : undefined
   const sets: string[] = []
   const params: Record<string, string | number> = { id: lead.id }
-  if (mapped && mapped !== lead.priority) {
+  if (mapped && mapped !== lead.priority && maySetPriority) {
     sets.push('priority = @priority')
     params.priority = mapped
   }
@@ -88,7 +116,21 @@ export async function analyzeLead(lead: LeadRow, actor: string): Promise<LeadAiR
     sets.push("updated_at = datetime('now')")
     db.prepare(`UPDATE leads SET ${sets.join(', ')} WHERE id = @id`).run(params)
   }
-  audit({ actor, action: 'ai.analyze_lead', entity: 'lead', entityId: lead.id, detail: { model: AI.model, qualification: a.qualification, priority: mapped, fit_score: fitScore } })
+  audit({
+    actor,
+    action: 'ai.analyze_lead',
+    entity: 'lead',
+    entityId: lead.id,
+    detail: {
+      model: AI.model,
+      qualification: a.qualification,
+      fit_score: fitScore,
+      priority: mapped,
+      // Record when the verdict was deliberately *not* applied, so the trail
+      // shows the human's ranking was respected rather than silently lost.
+      priority_applied: !!params.priority,
+    },
+  })
   return db.prepare('SELECT * FROM lead_ai WHERE lead_id = ?').get(lead.id) as unknown as LeadAiRow
 }
 

api/src/ai/prompts.ts

@@ -14,6 +14,24 @@ Rechtliche Leitplanken (IMMER einhalten):
 - Erfinde keine Fakten über den Empfänger. Nutze nur, was in den Lead-Daten steht.
 `.trim()
 
+// The one rule that decides whether the CRM stays trustworthy over time. Kept
+// short on purpose: it has to survive in the context of a small local model,
+// where every extra line pushes the actual task further down.
+export const EVIDENCE_RULES = `
+Umgang mit Fakten:
+- Schreibe nie einen Wert, den du nicht in einer Quelle gelesen hast. Ein leeres
+  Feld ist besser als ein selbstbewusst falsches.
+- Belegte Beobachtungen hältst du mit \`record_fact\` fest — mit \`detail\`, also
+  dem, was die Quelle wörtlich hergab. Erfinde niemals einen Beleg.
+- "primary" ist nur, was der Betrieb selbst über sich sagt (Impressum, Signatur,
+  eigene Antwort). Suchtreffer und Erwähnungen Dritter sind "supporting".
+- Von Hand gesetzte Werte überschreibt das System nicht. Weicht deine Quelle ab,
+  wird daraus ein Vorschlag zur Prüfung — das ist der gewollte Ausgang, kein
+  Fehler. Versuche nicht, ihn zu umgehen.
+- Woher ein gespeicherter Wert stammt, zeigt \`list_facts\`. Prüfe das, bevor du
+  einem Feld vertraust oder es infrage stellst.
+`.trim()
+
 export const COPILOT_SYSTEM = `
 Du bist der KI-Kern von OpenLeads — einer selbst gehosteten Vertriebs- und
 Rechnungs-Suite. Der Betrieb, für den du arbeitest, ist eine Webagentur, die
@@ -45,12 +63,14 @@ Arbeitsweise:
 - „Vertrag" meint ein Vertragsdokument (\`create_contract\`), nicht die Pipeline.
   Frische Verträge sind Entwürfe; finalisieren (Nummer + AGB einfrieren) nur auf
   ausdrücklichen Wunsch und nach Klartext-Bestätigung.
-- Soll aus einer oder mehreren URLs ein Lead entstehen, lege ihn direkt an: pro
-  URL einmal \`fetch_website\` (Firma/Kontakt auslesen), dann \`create_lead\`. Frage
-  NICHT nach Firma/Ort/Gewerk, wenn die Website sie liefert — nur \`website\` ist
-  Pflicht. Bewerte neue Leads standardmäßig voll mit (\`create_lead\` mit
-  \`analyze: true\`): das qualifiziert den Lead und setzt die Priorität aus dem
-  Ergebnis, statt sie auf „mittel“ zu lassen.
+- Soll aus einer oder mehreren URLs ein Lead entstehen, genügt PRO URL EIN
+  Aufruf: \`create_lead({ website, research: true, analyze: true })\`. Das wertet
+  Startseite und Impressum aus, füllt Firma/Ort/Kontakt/Technik belegt und
+  bewertet den Lead anschließend. Frage NICHT nach Firma, Ort oder Gewerk — das
+  Impressum liefert sie. Nur \`website\` ist Pflicht.
+- Willst du eine Seite nur ansehen, ohne etwas zu speichern, nimm
+  \`research_company\`. Einen bereits angelegten Lead recherchierst du mit
+  \`research_lead\` nach.
 - „Tab“, „Spalte“, „Section“, „Phase“ oder „Stage“ meinen die Pipeline-Stage (die
   gültigen Werte stehen im Tool-Schema von \`stage\`). Soll ein Lead in eine
   bestimmte Spalte (z. B. „ins Angebot“), setze beim Anlegen \`stage\` bzw. nutze
@@ -76,6 +96,8 @@ Arbeitsweise:
 - Geldbeträge sind in Cent (Ganzzahl) gespeichert; rechne sauber.
 - Wenn Daten fehlen, frage gezielt nach statt zu raten.
 
+${EVIDENCE_RULES}
+
 ${COMPLIANCE_GUARDRAILS}
 `.trim()