tegwick cf57a9bb50

CI Smoke / host-smoke (push) Successful in 0s

Details

CI Smoke / container-smoke (push) Successful in 4s

Details

docs(scope): fill in SCOPE.md — resolves C-30 staleness

Replace the unfilled template with the umbrella's actual boundary:
app/viewer/session + anchoring/evidence/binders in scope; headless
ingest (evidence-source) and contracts (citation-engine) out of scope.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-07-08 21:02:54 +02:00

3.8 KiB

Raw Blame History

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)

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

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.

3.8 KiB Raw Blame History