From cf57a9bb505a0da33c1ac9cc78f12e81397e1fa1 Mon Sep 17 00:00:00 2001
From: tegwick <bernd.worsch@gmail.com>
Date: Wed, 8 Jul 2026 21:02:54 +0200
Subject: [PATCH] =?UTF-8?q?docs(scope):=20fill=20in=20SCOPE.md=20=E2=80=94?=
 =?UTF-8?q?=20resolves=20C-30=20staleness?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 SCOPE.md | 116 ++++++++++++++++++++++++-------------------------------
 1 file changed, 50 insertions(+), 66 deletions(-)

diff --git a/SCOPE.md b/SCOPE.md
index d48e39a..25e96ec 100644
--- a/SCOPE.md
+++ b/SCOPE.md
@@ -8,130 +8,114 @@
 
 ## One-liner
 
-<!-- Describe the purpose of this repository in one precise sentence. -->
-<!-- Example: "Provides a lightweight event router for Kubernetes-native systems." -->
+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
 
-<!-- What is the main capability or idea behind this repository? -->
-<!-- What problem does it try to solve? -->
+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
 
-<!-- What this repository is responsible for. -->
-<!-- Be explicit and concrete. -->
-
--
--
--
+- 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
 
-<!-- What this repository deliberately does NOT do. -->
-<!-- This is often more important than "In 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
 
-<!-- When should someone consider using or exploring this repository? -->
-
--
--
--
+- 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
 
-<!-- When should someone ignore this repository? -->
-
--
--
--
+- 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
 
-<!-- Rough indication of maturity. No strict format required. -->
+- Status: active
+- Implementation: substantial (umbrella-first MVP functional; 125-test suite green)
+- Stability: evolving (subsystems being extracted into standalone repos)
+- Usage: internal / personal (MVP)
 
-- Status: <!-- e.g. concept / experimental / active / stable / deprecated -->
-- Implementation: <!-- e.g. idea / partial / substantial / complete -->
-- Stability: <!-- e.g. unstable / evolving / stable -->
-- Usage: <!-- e.g. none / personal / internal / production -->
-
-<!-- Add any notes that help set expectations. -->
+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
 
-<!-- Where does this repository sit in the bigger picture? -->
-
-- Upstream dependencies:
-- Downstream consumers:
-- Often used with:
+- 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
 
-<!-- Terms that are important to understand this repo. -->
-<!-- Especially useful if naming differs from other repos. -->
-
-- Preferred terms:
-- Also known as:
-- Potentially confusing terms:
+- 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
 
-<!-- List repositories that have similar or adjacent responsibilities. -->
-<!-- Helps detect duplication and navigate the ecosystem. -->
-
-- <repo-name> — <!-- how it relates -->
+- `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
 
-<!-- If someone decides to look deeper, where should they start? -->
-
-- Start with:
-- Key files / directories:
-- Entry points:
+- 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
 
-<!-- What can this repo's domain provide to other domains on request? -->
-<!-- Each capability block is parsed by the state-hub capability catalog ingest. -->
-<!-- Remove the examples and add your own, or leave empty if none. -->
-
-<!--
-```capability
-type: infrastructure
-title: Example capability title
-description: What this capability provides, in one or two sentences.
-keywords: [keyword1, keyword2, keyword3]
-```
--->
+<!-- The reusable ingest capability now lives in evidence-source's registry.
+     This umbrella currently exposes no standalone capability of its own. -->
 
 ---
 
 ## Notes
 
-<!-- Anything else worth knowing. Keep it short. -->
+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.