# SCOPE

> This file helps you quickly understand what this repository is about,
> when it is relevant, and when it is not.
> It is intentionally lightweight and may be incomplete.

---

## One-liner

Document-centered evidence workspace — the umbrella app that lets a user open
documents, capture selections as durable citations, and organize them into
evidence sets and binders.

---

## Core Idea

Turn a pile of source documents into traceable evidence. A user opens a
document, highlights a passage, and the app captures a durable, re-resolvable
selector plus the surrounding context. Those captures become citations that can
be linked, grouped into evidence sets, and exported. During the umbrella-first
MVP the app also hosts subsystems that are being extracted into their own repos
as they stabilize.

---

## In Scope

- The application shell, viewer, and session management (upload, sample
  sessions, export/re-import ZIP)
- Anchoring: creating and resolving selectors against document representations
- Evidence capture, evidence links, evidence sets, citation cards, and binders
- Viewer URL resolution and blob-vs-fixture policy for uploaded PDFs
- The source ↔ anchor round-trip integration contract

---

## Out of Scope

- Headless document ingest / fingerprinting / extraction — owned by
  `evidence-source` (consumed here via the `@source` façade)
- The shared domain model and engine services — owned by `citation-engine`
  (`@citation-evidence/engine`)
- Persisting evidence to a server backend (MVP is browser/session-local)

---

## Relevant When

- You are working on the end-user evidence workflow (capture, link, organize)
- You are changing the viewer, session lifecycle, or app UI
- You need the integration surface that ties ingest, anchoring, and binders together

---

## Not Relevant When

- You need to change how documents are ingested/extracted (see `evidence-source`)
- You need to change the `Document`/selector/evidence contracts (see `citation-engine`)

---

## Current State

- Status: active
- Implementation: substantial (umbrella-first MVP functional; 125-test suite green)
- Stability: evolving (subsystems being extracted into standalone repos)
- Usage: internal / personal (MVP)

The PDF ingest slice was extracted into `evidence-source` (ESRC-WP-0001) and is
now consumed across the repo boundary. No umbrella-owned workplans are currently
open; active change is driven from the extracted subsystem repos.

---

## How It Fits

- Upstream dependencies: `citation-engine` (contracts + engine), `evidence-source` (PDF ingest)
- Downstream consumers: end users of the evidence workspace
- Often used with: `citation-engine`, `evidence-source`

---

## Terminology

- Preferred terms: citation, selector, evidence set, binder, representation
- Also known as: "the umbrella" / "the app"
- Potentially confusing terms: "source" (here means the app's `src/source`
  façade over `evidence-source`, not raw source documents)

---

## Related / Overlapping Repositories

- `citation-engine` — shared domain model and engine services this app builds on
- `evidence-source` — headless PDF ingest extracted from this repo's `src/source`

---

## Getting Oriented

- Start with: `README.md`, then `wiki/ArchitectureOverview.md`
- Key files / directories: `src/app/` (shell + sessions), `src/anchor/`
  (selectors), `src/binder/`, `src/work/` (session/engine context)
- Entry points: the Vite app (`pnpm dev`); `tests/integration/` for end-to-end contracts

---

## Provided Capabilities

<!-- The reusable ingest capability now lives in evidence-source's registry.
     This umbrella currently exposes no standalone capability of its own. -->

---

## Notes

Subsystems graduate from `src/` into sibling repos as they stabilize
(`citation-engine`, `evidence-source`); the umbrella keeps app/viewer/session
concerns and the cross-subsystem integration tests.