From 56e29ae1bf9b19613370c2f4ffdd0aa01495c104 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Sun, 24 May 2026 15:53:28 +0200
Subject: [PATCH] Seeded INTENT.md

---
 INTENT.md | 459 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |   4 +-
 2 files changed, 460 insertions(+), 3 deletions(-)
 create mode 100644 INTENT.md

diff --git a/INTENT.md b/INTENT.md
new file mode 100644
index 0000000..948effe
--- /dev/null
+++ b/INTENT.md
@@ -0,0 +1,459 @@
+# INTENT
+
+## Purpose
+
+This repository exists to provide the evidence binding layer for the **citation-evidence** ecosystem.
+
+**evidence-binder** connects evidence items to structured targets such as form fields, claims, requirements, decisions, document sections, tasks, or other information objects.
+
+It is responsible for answering the binding question:
+
+> What does this evidence support, explain, contradict, or source?
+
+---
+
+## Primary Utility
+
+The repository provides the model and interaction logic for turning collected evidence into structured support for information work.
+
+It should make it possible to:
+
+- link evidence items to form fields,
+- link evidence items to claims, requirements, decisions, or document sections,
+- group evidence items into evidence sets,
+- express relation types such as supports, contradicts, explains, qualifies, or source-for,
+- track evidence status and confidence per target,
+- switch between multiple evidence items connected to the same target,
+- coordinate active target, active evidence item, and active source annotation,
+- support visual guidance from structured target to evidence to source context.
+
+This repository turns collected citations into actionable evidence relationships.
+
+---
+
+## Intended Users
+
+Primary users of this repository are developers and agents implementing evidence-backed workflows.
+
+They include:
+
+- developers building evidence-backed forms,
+- developers building claim or requirement review tools,
+- developers implementing source-backed decision workflows,
+- developers connecting document evidence to structured data,
+- coding agents helping users identify, bind, inspect, or validate evidence,
+- application developers integrating citation-evidence into domain-specific systems.
+
+End users should experience this repository whenever they see which source passage supports a field, claim, requirement, or decision.
+
+---
+
+## Strategic Role
+
+The strategic role of **evidence-binder** is to make citation-evidence more than a document annotation system.
+
+Annotations and evidence items become much more valuable when they are connected to the things they justify.
+
+This repository provides that connection.
+
+It enables the flow:
+
+```text
+Evidence Item
+  → Evidence Link
+  → Evidence Target
+  → Evidence Set
+  → Supported Field / Claim / Requirement / Decision
+````
+
+The repository should make it possible to inspect not only where evidence came from, but also what it is being used for.
+
+---
+
+## Core Concept
+
+The core concept of this repository is the **evidence link**.
+
+An evidence link connects an evidence item to a structured target with a meaningful relation.
+
+Examples:
+
+```text
+Evidence Item A supports Form Field X
+Evidence Item B contradicts Claim Y
+Evidence Item C explains Requirement Z
+Evidence Item D is the source for Decision Q
+Evidence Item E qualifies Document Section S
+```
+
+The evidence link is not just a technical pointer. It expresses an interpretive relationship between source material and structured work.
+
+---
+
+## Scope
+
+This repository should own:
+
+* evidence-to-target binding model,
+* evidence link lifecycle,
+* evidence sets,
+* target adapters,
+* relation types,
+* target evidence status,
+* field evidence state,
+* active target and active evidence state,
+* evidence switching behavior,
+* evidence completeness indicators,
+* support for multiple evidence items per target,
+* support for evidence that supports or contradicts a target,
+* visual guide model connecting target, evidence card, and source highlight,
+* interaction contracts for evidence-backed forms and structured review workflows.
+
+It should provide the binding capabilities consumed by:
+
+* **citation-evidence** for the integrated workspace,
+* **citation-work** when collected evidence is prepared for later use,
+* **citation-engine** through shared domain contracts,
+* **evidence-anchor** when linked evidence must reopen source context,
+* **evidence-source** when evidence requires source context metadata.
+
+---
+
+## Out of Scope
+
+This repository should not own the broader system internals.
+
+Specifically, it should not own:
+
+* the canonical document and annotation model,
+* document ingestion,
+* text extraction,
+* citation recovery,
+* low-level selector resolution,
+* viewer-specific highlighting,
+* review workspace UI,
+* citation card rendering internals,
+* persistence implementation details,
+* application shell and deployment,
+* domain-specific form schemas beyond generic target adapters.
+
+Those responsibilities belong to the appropriate citation-evidence subsystem repositories.
+
+---
+
+## Architectural Position
+
+```text
+citation-evidence
+  integrated product shell and reference workspace
+
+citation-engine
+  core domain model, services, persistence contracts
+
+evidence-binder
+  evidence links, evidence sets, target binding, active evidence state
+
+citation-work
+  document review and evidence capture workflow
+
+evidence-anchor
+  selector resolution and source-context highlighting
+
+evidence-source
+  document ingestion, representations, and source context
+```
+
+**evidence-binder** sits between evidence objects and the structured targets that use them.
+
+It should not define what documents are or how annotations resolve. It should define how evidence is attached to meaningful targets.
+
+---
+
+## Primary Workflows
+
+### 1. Link Evidence to a Form Field
+
+A user selects an evidence item and attaches it to a form field.
+
+```text
+Active Form Field
+  → Select Evidence Item
+  → Create Evidence Link
+  → Mark Relation as supports / explains / source-for
+  → Update Field Evidence State
+```
+
+### 2. Focus Field and Show Evidence
+
+A user activates a field that has linked evidence.
+
+```text
+Focus Form Field
+  → Load Evidence Set
+  → Select Active Evidence Item
+  → Request Source Context
+  → Highlight Evidence Card
+  → Highlight Source Annotation
+```
+
+### 3. Switch Between Evidence Items
+
+A target has several evidence items. The user switches between them.
+
+```text
+Evidence Set
+  → Next / Previous Evidence Item
+  → Update Active Evidence
+  → Resolve Annotation
+  → Scroll Source Viewer
+  → Update Visual Guide
+```
+
+### 4. Bind Evidence to a Claim or Requirement
+
+Evidence is linked to a structured non-form target.
+
+```text
+Claim / Requirement / Decision
+  → Attach Evidence Item
+  → Set Relation
+  → Set Status / Confidence
+  → Make Evidence Traceable
+```
+
+### 5. Inspect Evidence Completeness
+
+A user or agent checks whether a target has sufficient evidence.
+
+```text
+Target
+  → Load Evidence Links
+  → Evaluate Required Evidence Policy
+  → Show none / candidate / confirmed / conflicting / insufficient
+```
+
+---
+
+## Target Model
+
+The repository should support generic evidence targets.
+
+Initial target types may include:
+
+```text
+form-field
+claim
+requirement
+decision
+document-section
+task
+record-field
+```
+
+The model should not assume that all targets are form fields.
+
+A target should be addressable through a generic structure such as:
+
+```ts
+type EvidenceTarget = {
+  type: string;
+  id: string;
+  label?: string;
+  context?: Record<string, unknown>;
+};
+```
+
+This allows domain-specific systems to add their own target types without changing the core binding model.
+
+---
+
+## Relation Types
+
+Initial evidence relations may include:
+
+```text
+supports
+contradicts
+explains
+source-for
+qualifies
+context-for
+derived-from
+needs-check
+```
+
+The first version should keep relation types simple but explicit.
+
+The relation should describe how the evidence item is being used with respect to the target.
+
+---
+
+## Evidence State
+
+The repository should support target-specific evidence state.
+
+Examples:
+
+```text
+no-evidence
+candidate-evidence
+confirmed-evidence
+conflicting-evidence
+insufficient-evidence
+needs-review
+verified
+```
+
+An evidence item may be generally confirmed, but its relationship to a specific target may still need review.
+
+Therefore, evidence item status and evidence link status should be distinguishable.
+
+---
+
+## Visual Guide Concept
+
+For evidence-backed form and structured review workflows, the user should be able to visually understand the connection between:
+
+```text
+structured target
+  → evidence item / citation card
+  → source annotation / highlighted passage
+```
+
+The repository should own the model and interaction state for this visual guide, not necessarily the final rendering implementation.
+
+A visual guide may use:
+
+```text
+active target rect
+active evidence card rect
+active annotation rect
+connector state
+focus state
+hover state
+selection state
+```
+
+Rendering may be done by an application layer using SVG, canvas, or DOM overlays.
+
+---
+
+## Design Principles
+
+### Evidence Links Are First-Class
+
+A binding between evidence and target is not just metadata. It is a meaningful domain object.
+
+### Evidence Is Reusable
+
+The same evidence item may support multiple targets.
+
+### Targets Are Generic
+
+The model should support form fields first, but not be limited to forms.
+
+### Relation Is Explicit
+
+The system should distinguish evidence that supports, contradicts, explains, qualifies, or merely sources a target.
+
+### Active State Is Shared
+
+Evidence-backed workflows require coordinated active state across field, evidence item, and document highlight.
+
+### Source Context Remains External
+
+The repository should request source context through **citation-engine** and **evidence-anchor**, not resolve highlights itself.
+
+### UI Logic Should Be Portable
+
+The binding model should be reusable in different interfaces: forms, claim review, requirements tools, audit trails, and reports.
+
+### Agent Compatibility
+
+Evidence links should be machine-readable so agents can inspect missing evidence, weak evidence, contradictions, and unsupported fields.
+
+---
+
+## Expected Dependencies
+
+This repository is expected to depend on shared types and contracts from:
+
+```text
+citation-engine
+  EvidenceItem, EvidenceLink, EvidenceSet, CitationTarget, service contracts
+```
+
+It may interact with:
+
+```text
+evidence-anchor
+  to request source resolution for active evidence
+
+citation-work
+  to receive collected evidence items
+
+evidence-source
+  to access source metadata and document context
+
+citation-evidence
+  to integrate evidence-backed forms and structured workflows
+```
+
+It should avoid direct dependency on viewer internals or document ingestion internals.
+
+---
+
+## First Useful Version
+
+A first useful version of **evidence-binder** should provide:
+
+* generic evidence target model,
+* evidence link model,
+* evidence set model,
+* relation type model,
+* target evidence state model,
+* simple in-memory binding service,
+* active target / active evidence state handling,
+* helper logic for linking evidence to form fields,
+* helper logic for listing evidence by target,
+* helper logic for switching active evidence,
+* initial visual guide state model.
+
+The first version does not need a full form renderer, but it should make evidence-backed form workflows possible.
+
+---
+
+## Success Criteria
+
+The repository is successful when another subsystem can use it to:
+
+1. define a structured target such as a form field,
+2. attach one or more evidence items to that target,
+3. describe the relation between evidence and target,
+4. retrieve all evidence for the target,
+5. activate one evidence item,
+6. coordinate target, evidence card, and source annotation state,
+7. indicate whether the target has sufficient evidence.
+
+A developer or coding agent should be able to understand from this repository how evidence becomes connected to structured work.
+
+---
+
+## Repository Character
+
+This repository should be:
+
+* relationship-focused,
+* target-neutral,
+* form-friendly but not form-limited,
+* explicit about evidence relations,
+* lightweight at first,
+* compatible with multiple UI shells,
+* useful for both human review and agentic inspection,
+* careful not to absorb document or anchoring responsibilities.
+
+---
+
+## Guiding Statement
+
+**evidence-binder exists to connect cited evidence to the structured things it supports.**
diff --git a/README.md b/README.md
index fcd7b8f..01537d1 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1 @@
-# repo-seed
-
-A git repository template to bootstrap coulomb projects from.
\ No newline at end of file
+Connect evidence items to structured targets such as form fields, claims, requirements.