Documentation, terminology repo cleanup.

docs/abstraction-strategy.md

@@ -55,7 +55,7 @@ truth.
 
 ## Trial Repo Observations
 
-`repo-registry` demonstrates the current boundary well: deterministic scanning sees
+`repo-scoping` demonstrates the current boundary well: deterministic scanning sees
 FastAPI routes, tests, docs, and Python structure, but the meaningful abstractions
 are repository ingestion, deterministic analysis, candidate review, discovery, and
 State Hub coordination. Those names likely require either review edits or LLM

docs/classification-strategy.md

@@ -1,6 +1,6 @@
 # Classification Strategy
 
-Repo-registry needs classification for orientation without pretending repository
+Repo-scoping needs classification for orientation without pretending repository
 behavior is always cleanly separable. The review UI should therefore support two
 layers of classification:
 

docs/operations.md

@@ -1,12 +1,13 @@
 # Operational Readiness
 
 This note captures the runtime knobs and baseline operating procedures for the
-Repository Ability Registry service.
+Repository Scoping service.
 
 ## Configuration
 
 Configuration is read from environment variables with the `REPO_REGISTRY_`
-prefix.
+prefix. That prefix is retained as an implementation compatibility detail after
+the product rename from Repository Ability Registry to Repository Scoping.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |

docs/scope-md-spec.md

@@ -4,7 +4,7 @@
 It answers, quickly and concretely, what the repository is for, when it is useful,
 where it fits, and what capabilities it can provide.
 
-Repo-registry is the source of truth for generating and validating `SCOPE.md`
+Repo-scoping is the source of truth for generating and validating `SCOPE.md`
 because its approved characteristic model already captures the same structure:
 
 ```text
@@ -14,7 +14,7 @@ Scope -> Ability -> Capability -> Feature -> Evidence -> Observed Fact
 This specification supersedes the Custodian dashboard reference at
 `state-hub/dashboard/src/docs/scope.md`. The scaffold template remains at
 `state-hub/scripts/project_rules/scope.template`; this document defines how
-repo-registry should generate, validate, and update that file.
+repo-scoping should generate, validate, and update that file.
 
 Related model docs:
 
@@ -41,12 +41,12 @@ It should answer:
 
 The historical Custodian reference calls this an "11-section template". The
 current `scope.template` contains twelve functional sections plus an optional
-`Notes` tail. Repo-registry should preserve the current template headings for
+`Notes` tail. Repo-scoping should preserve the current template headings for
 compatibility and treat `Notes` as curator-owned free text.
 
 Generated files must contain these sections, in this order:
 
-| Section | Source in repo-registry | Generation ownership |
+| Section | Source in repo-scoping | Generation ownership |
 |---------|--------------------------|----------------------|
 | `## One-liner` | Scope name plus scope description | generated, curator-reviewed |
 | `## Core Idea` | Scope description and top approved abilities | generated, curator-reviewed |
@@ -101,7 +101,7 @@ Suggested form:
 
 ### Out of Scope
 
-This section is primarily curator-owned. Repo-registry may seed it from
+This section is primarily curator-owned. Repo-scoping may seed it from
 classification expectation gaps whose `expected_type` is one of:
 
 - `classification-granularity`
@@ -225,7 +225,7 @@ requested.
 
 ## Generation Ownership
 
-Repo-registry-generated sections:
+Repo-scoping-generated sections:
 
 - One-liner
 - Core Idea
@@ -258,7 +258,7 @@ The validator should mirror the Custodian DOI C5 checks:
 - C5c: `## Provided Capabilities` contains parseable `capability` blocks, or an
   explicit empty-state note when the repo provides no routable capabilities.
 
-Additional repo-registry validation:
+Additional repo-scoping validation:
 
 - Generated sections with missing data must include `<!-- needs curator input -->`.
 - Capability blocks must parse as key/value metadata.

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.