Documentation, terminology repo cleanup.

docs/terminology.md

@@ -0,0 +1,60 @@
+# Repository Scoping Terminology
+
+Repository Scoping turns repositories into reviewable, source-linked orientation
+maps. The goal is not to infer every possible product story automatically; it is
+to give humans and trusted agents a durable structure for understanding what a
+repository is for and how that claim is supported.
+
+## Product Identity
+
+- Repository Scoping is the product and UI name.
+- `repo-scoping` is the managed repository slug, Git remote identity, and State
+  Hub repository identity.
+- `repo_registry`, `REPO_REGISTRY_`, and `var/repo-registry.sqlite3` are retained
+  compatibility names in code and local configuration.
+- Repository Ability Registry and `repo-registry` are historical names from
+  before the scope-oriented rename.
+
+## Characteristic Model
+
+A characteristic is any curated statement about a repository at one of the main
+abstraction levels. The preferred orientation is a mostly tree-shaped model:
+
+```text
+Scope -> Ability -> Capability -> Feature -> Evidence -> Observed fact
+```
+
+Real repositories are messier than a perfect tree. Evidence may therefore refer
+to facts or to lower-granularity characteristics. Same-level references are
+allowed when useful, but they are also signals that the hierarchy may need manual
+normalization.
+
+## Terms
+
+- Scope: the one root characteristic describing what the repository is about and
+  where it is relevant.
+- Ability: a high-level useful outcome the repository can provide.
+- Capability: a more concrete thing the repository can do in support of an
+  ability.
+- Feature: a user-facing, API-facing, backend, UI, or operational behavior that
+  contributes to a capability.
+- Evidence: a support link for a characteristic. Evidence can point to observed
+  facts or to lower-level characteristics.
+- Observed fact: deterministic scanner output such as files, manifests,
+  languages, tests, APIs, routes, commands, or documentation references.
+- Candidate: proposed characteristic or evidence from deterministic heuristics
+  or optional LLM assistance. Candidates are review inputs, not registry truth.
+- Approved: curated registry truth that appears in ability maps, search, exports,
+  and SCOPE generation.
+- Rejected: a candidate judged false or irrelevant. Rejected entries are hidden
+  by default but retained for audit and recovery.
+- Classification: a main type plus optional additional attributes that help
+  users filter and orient without forcing every item into a single rigid box.
+
+## Extraction Philosophy
+
+Deterministic scanning should remain useful without LLM support. Optional LLM
+assistance is used as a comparison and acceleration layer: when model-assisted
+expectations reveal missing concepts, the deterministic scanner and heuristics
+should be improved over time. This creates a feedback loop where repository
+inspection, manual curation, and optional model output co-evolve.