This repository exists to provide the document review workspace for the **citation-evidence** ecosystem.
**citation-work** enables users to review collections of documents, mark relevant passages, add commentary, and create reusable evidence items that can later support form fields, claims, requirements, decisions, reports, or web publications.
It is the human-facing workbench for turning document reading into structured evidence.
---
## Primary Utility
The repository provides the review and annotation user experience for citation-evidence.
It should make it easy to:
- open and navigate document collections,
- review documents efficiently,
- select relevant passages,
- create annotations,
- add commentary,
- convert annotations into evidence items,
- browse collected evidence,
- navigate from evidence items back to source context,
- prepare evidence for later binding, export, or citation rendering.
This repository turns the core model from **citation-engine** and the anchoring capabilities from **evidence-anchor** into a practical working environment.
---
## Intended Users
Primary users are people who need to read documents and collect useful, source-backed evidence.
They include:
- researchers and analysts reviewing document sets,
- consultants and knowledge workers preparing reports,
- compliance, audit, procurement, and legal-adjacent workers collecting source support,
- product and requirements workers extracting evidence from source material,
- form workers preparing evidence before structured data entry,
- developers and coding agents building review workflows on top of citation-evidence.
End users should experience this repository as the place where document review happens.
---
## Strategic Role
The strategic role of **citation-work** is to provide the first usable surface of the citation-evidence system.
It should prove that the system can support a complete evidence capture loop:
```text
Document Collection
→ Document Viewer
→ Text Selection
→ Annotation
→ Commentary
→ Evidence Item
→ Evidence Sidebar
→ Reopen Source Context
````
The repository should focus on workflow quality: reducing friction between reading, noticing, marking, commenting, and later reusing evidence.
---
## Core Concept
The central concept of **citation-work** is the **review workspace**.
A review workspace combines:
* a document collection,
* a document viewer,
* an annotation creation workflow,
* an evidence sidebar,
* review status,
* search and filtering,
* navigation back to source context.
The workspace should help users move from unstructured reading to structured evidence without interrupting concentration.
---
## Scope
This repository should own:
* document collection review UI,
* document list and navigation UI,
* review queue behavior,
* document viewer shell composition,
* annotation toolbar and selection UX,
* evidence sidebar,
* evidence item browsing,
* review status interactions,
* evidence status interactions,
* tagging and filtering UI,
* navigation from evidence item to source context,
* review-oriented keyboard shortcuts,
* user workflows for collecting evidence before later binding or export.
It should consume domain services and types from **citation-engine** and anchoring/viewer contracts from **evidence-anchor**.
---
## Out of Scope
This repository should not own the lower-level or broader system concerns.
Specifically, it should not own:
* the canonical domain model,
* persistence contracts,
* low-level selector resolution algorithms,
* PDF text extraction internals,
* Markdown or HTML ingestion pipelines,
* external source discovery,
* citation recovery logic,
* form-field binding semantics,
* visual guide overlay logic for evidence-backed forms,
* citation card rendering internals,
* product-level deployment and integration shell.
Those responsibilities belong to the appropriate subsystem repositories.
---
## Architectural Position
```text
citation-evidence
integrated product shell and reference application
The interface should minimize friction between reading, marking, commenting, and moving on.
### Evidence Visibility
Collected evidence should remain visible enough that users understand what has already been captured.
### Source Context Is Always Recoverable
Every evidence item should provide a direct path back to the source passage.
### Format Neutrality
The review experience should work across PDFs, Markdown, HTML, and future document formats through viewer adapters.
### Domain Alignment
The repository should use concepts from **citation-engine** rather than inventing parallel local models.
### Anchoring Delegation
Selector creation, resolution, and re-anchoring should be delegated to **evidence-anchor**.
### Progressive Complexity
The first version should support a simple review loop before adding advanced search, collaboration, or automated suggestions.
### Agent Compatibility
The workflow should be explicit enough that agentic assistants can help find candidate evidence, summarize marked passages, propose tags, or identify missing evidence.
for integration shell during reference app development
```
It should avoid direct dependency on **evidence-binder** unless building a review-to-binding bridge. Binding-specific behavior should remain outside the core review workspace.
---
## First Useful Version
A first useful version of **citation-work** should provide:
* a simple document collection view,
* a PDF document viewer shell,
* text selection capture through an adapter,
* annotation creation flow,
* commentary input,
* evidence item creation through **citation-engine**,
* evidence sidebar,
* click evidence item to reopen highlighted source context,
* basic document and evidence status display.
This version should prove that a user can review a document and produce reusable evidence.
---
## Success Criteria
The repository is successful when a user can efficiently perform the basic evidence capture loop:
1. open a document collection,
2. select a document,
3. read the document,
4. mark a relevant passage,
5. add commentary,
6. save it as evidence,
7. see it in the evidence sidebar,
8. return to the cited passage by clicking the evidence item.
A developer or coding agent should also be able to understand which parts of the workflow belong here and which belong to the underlying subsystems.
---
## Repository Character
This repository should be:
* user-workflow-oriented,
* interface-focused,
* thin over the domain engine,
* explicit about review concepts,
* careful not to absorb core model responsibilities,
* friendly to fast MVP iteration,
* suitable for later integration into the umbrella product shell.
