Documentation, terminology repo cleanup.

README.md

@@ -1,12 +1,12 @@
-# Repository Ability Registry
+# Repository Scoping
 
-The Repository Ability Registry maps repositories from usefulness to implementation:
+Repository Scoping maps repositories from usefulness to implementation:
 
 ```text
 Ability -> Capability -> Feature -> Evidence -> Code location
 ```
 
-The first implementation slice is a Python registry core plus FastAPI HTTP API and a small curator UI. Repository registration imports basic metadata from the repository itself, then analysis builds observed facts and candidate review entries.
+The implementation is a Python registry core plus FastAPI HTTP API and a small curator UI. Repository registration imports basic metadata from the repository itself, then analysis builds observed facts and candidate review entries.
 
 ## Local Development
 
@@ -30,7 +30,7 @@ Run the API:
 uvicorn repo_registry.web_api.app:app --reload
 ```
 
-The API creates a local SQLite database at `var/repo-registry.sqlite3` by default.
+The API creates a local SQLite database at `var/repo-registry.sqlite3` by default. The database path, `REPO_REGISTRY_` environment prefix, and `repo_registry` Python package name remain compatibility details after the product rename to Repository Scoping.
 
 ## First API Loop
 

SCOPE.md

@@ -1,7 +1,7 @@
 ---
 domain: capabilities
 repo: repo-scoping
-updated: "2026-04-30"
+updated: "2026-05-01"
 ---
 
 # SCOPE
@@ -169,7 +169,7 @@ keywords: [scope, scope-md, update, diff, staleness]
 
 ## Notes
 
-- The local checkout path is still `/home/worsch/repo-registry`; the canonical
+- The product and managed repository identity are Repository Scoping /
-  State Hub slug and Git remote are now `repo-scoping`.
+  `repo-scoping`.
-- Ecosystem-wide SCOPE.md refresh is blocked until Custodian C5b/C5c checks are
+- The Python package name `repo_registry`, `REPO_REGISTRY_` environment prefix,
-  active and more managed repos have approved characteristics in repo-scoping.
+  and default SQLite filename remain compatibility details.

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.

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "repo-registry"
 version = "0.1.0"
-description = "Repository Ability Registry"
+description = "Repository Scoping"
 readme = "README.md"
 requires-python = ">=3.12"
 dependencies = [

src/repo_registry/__init__.py

@@ -1,4 +1,4 @@
-"""Repository Ability Registry."""
+"""Repository Scoping."""
 
 __all__ = ["__version__"]
 

src/repo_registry/scope/generator.py

@@ -57,7 +57,7 @@ class ScopeGenerator:
             "",
             "> This file helps you quickly understand what this repository is about,",
             "> when it is relevant, and when it is not.",
-            "> It was generated from approved repo-registry characteristics.",
+            "> It was generated from approved repo-scoping characteristics.",
             "",
             "---",
             "",

src/repo_registry/web_api/app.py

@@ -113,7 +113,7 @@ def get_service(settings: Settings = Depends(get_settings)) -> RegistryService:
 
 API_DESCRIPTION = (
     "Register repositories, analyze their observable implementation facts, "
-    "curate reviewable ability graphs, and search approved repository abilities."
+    "curate reviewable scope graphs, and search approved repository characteristics."
 )
 
 OPENAPI_TAGS = [
@@ -128,7 +128,7 @@ OPENAPI_TAGS = [
 ]
 
 app = FastAPI(
-    title="Repository Ability Registry",
+    title="Repository Scoping",
     version="0.1.0",
     description=API_DESCRIPTION,
     openapi_tags=OPENAPI_TAGS,

src/repo_registry/web_ui/views.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from dataclasses import asdict
 from html import escape
+from pathlib import Path
 from urllib.parse import quote_plus
 
 from fastapi import APIRouter, Depends, Form, HTTPException, Query
@@ -13,6 +14,7 @@ from repo_registry.web_api.app import get_service
 
 
 router = APIRouter(include_in_schema=False)
+APP_NAME = "Repository Scoping"
 
 
 def page(title: str, body: str) -> HTMLResponse:
@@ -23,7 +25,7 @@ def page(title: str, body: str) -> HTMLResponse:
           <head>
             <meta charset="utf-8">
             <meta name="viewport" content="width=device-width, initial-scale=1">
-            <title>{escape(title)} · Repository Ability Registry</title>
+            <title>{escape(title)} · {APP_NAME}</title>
             <style>
               :root {{
                 color-scheme: light;
@@ -151,6 +153,18 @@ def page(title: str, body: str) -> HTMLResponse:
               .tree ul {{ margin: 8px 0 0 20px; padding: 0; }}
               .tree li {{ margin: 6px 0; }}
               .source {{ color: var(--muted); font-family: ui-monospace, SFMono-Regular, Consolas, monospace; font-size: 12px; }}
+              .scope-document {{
+                margin: 0;
+                padding: 16px;
+                overflow-x: auto;
+                white-space: pre-wrap;
+                overflow-wrap: anywhere;
+                border: 1px solid var(--line);
+                border-radius: 8px;
+                background: #fbfcfd;
+                color: #1f2933;
+                font: 13px/1.55 ui-monospace, SFMono-Regular, Consolas, monospace;
+              }}
               .actions {{ display: flex; gap: 8px; flex-wrap: wrap; align-items: center; }}
               [data-pending] {{ display: none; color: var(--muted); }}
               form.is-submitting [data-pending] {{ display: inline; }}
@@ -168,10 +182,11 @@ def page(title: str, body: str) -> HTMLResponse:
           </head>
           <body>
             <header>
-              <a href="/ui"><strong>Repository Ability Registry</strong></a>
+              <a href="/ui"><strong>{APP_NAME}</strong></a>
               <nav class="actions">
                 <a href="/ui/search">Search</a>
                 <a href="/ui/discovery">Discovery</a>
+                <a href="/ui/scope">SCOPE</a>
                 <a href="/docs">API Docs</a>
               </nav>
             </header>
@@ -262,6 +277,24 @@ def repository_index(service: RegistryService = Depends(get_service)) -> HTMLRes
     return render_repository_index(service)
 
 
+@router.get("/ui/scope")
+def scope_document() -> HTMLResponse:
+    scope_path = Path("SCOPE.md")
+    if scope_path.exists():
+        content = scope_path.read_text(encoding="utf-8")
+        rendered = f'<pre class="scope-document">{escape(content)}</pre>'
+    else:
+        rendered = '<p class="muted">No SCOPE.md file was found in this checkout.</p>'
+    body = f"""
+    <h1>SCOPE.md</h1>
+    <section class="panel stack">
+      <p class="muted">Canonical scope summary for this repository.</p>
+      {rendered}
+    </section>
+    """
+    return page("SCOPE.md", body)
+
+
 @router.get("/ui/discovery")
 def discovery_page(service: RegistryService = Depends(get_service)) -> HTMLResponse:
     repositories = service.list_repositories()

tests/test_web_api.py

@@ -11,7 +11,7 @@ def test_openapi_groups_agent_facing_endpoints():
 
     assert response.status_code == 200
     schema = response.json()
-    assert schema["info"]["title"] == "Repository Ability Registry"
+    assert schema["info"]["title"] == "Repository Scoping"
     assert schema["info"]["version"] == "0.1.0"
     assert {tag["name"] for tag in schema["tags"]} >= {
         "repositories",
@@ -303,10 +303,31 @@ def test_docs_endpoint_is_available():
     response = client.get("/docs")
 
     assert response.status_code == 200
-    assert "Repository Ability Registry" in response.text
+    assert "Repository Scoping" in response.text
     assert "openapi.json" in response.text
 
 
+def test_ui_uses_repository_scoping_brand():
+    client = TestClient(app)
+
+    response = client.get("/ui")
+
+    assert response.status_code == 200
+    assert "Repository Scoping" in response.text
+    assert "Repository Ability Registry" not in response.text
+
+
+def test_ui_scope_page_presents_scope_md():
+    client = TestClient(app)
+
+    response = client.get("/ui/scope")
+
+    assert response.status_code == 200
+    assert "SCOPE.md" in response.text
+    assert "scope.generate" in response.text
+    assert "repo-scoping" in response.text
+
+
 def test_health_reports_database_and_checkout_root(tmp_path):
     def override_settings():
         return Settings(

wiki/AbilityExtractionHeuristics.md

@@ -4,7 +4,7 @@ AbilityExtractionHeuristics
 
 # Ability / Capability Extraction Heuristics v0.1
 
-## Repository Ability Registry
+## Repository Scoping
 
 ## 1. Purpose
 

wiki/ArchitectureSketch.md

@@ -1,8 +1,8 @@
 ArchitectureSketch
 
-* Repository Ability Registry — Architecture v0.1*
+* Repository Scoping — Architecture v0.1*
 
-# Repository Ability Registry — Architecture v0.1
+# Repository Scoping — Architecture v0.1
 
 ## 1. Core architectural idea
 

wiki/FunctionalRequirementsSpecV0.1.md

@@ -1,14 +1,14 @@
 FunctionalRequirementsSpecV0.1 
 
-*Repository Ability Registry Functionality*
+*Repository Scoping Functionality*
 
-Here is a **Functional Requirements Specification (FRS)** for the **Repository Ability Registry (v0.1)**—focused strictly on **externally observable system behavior**, aligned with your architecture and PRD.
+Here is a **Functional Requirements Specification (FRS)** for the **Repository Scoping (v0.1)**—focused strictly on **externally observable system behavior**, aligned with your architecture and PRD.
 
 ---
 
 # **Functional Requirements Specification (FRS)**
 
-## **Repository Ability Registry v0.1**
+## **Repository Scoping v0.1**
 
 ---
 

wiki/LandingPage.md

@@ -1,8 +1,8 @@
 LandingPage
 
-*Introducing the Repository Ability Registry*
+*Introducing the Repository Scoping*
 
-# **Repository Ability Registry**
+# **Repository Scoping**
 
 ## **Understand What Code Can Do. Instantly.**
 
@@ -26,7 +26,7 @@ Every day, developers and architects face the same problem:
 
 ## **What if repositories could explain themselves?**
 
-The **Repository Ability Registry** transforms Git repositories into **structured, inspectable knowledge**.
+The **Repository Scoping** transforms Git repositories into **structured, inspectable knowledge**.
 
 It reveals:
 
@@ -95,7 +95,7 @@ The registry provides a shared, machine-readable understanding.
 
 Between raw code and real-world usefulness, there is a gap.
 
-The **Repository Ability Registry** fills it.
+The **Repository Scoping** fills it.
 
 ---
 

wiki/ProductRequirementsSpecificationV0.1.md

@@ -1,16 +1,16 @@
 ProductRequirementsSpecV0.1
 
-*Repository Ability Registry Requirements*
+*Repository Scoping Requirements*
 
 # **Product Requirements Document (PRD)**
 
-## **Repository Ability Registry (v0.1)**
+## **Repository Scoping (v0.1)**
 
 ---
 
 # 1. **Purpose**
 
-The **Repository Ability Registry** provides a structured, inspectable orientation layer for code repositories by mapping them from **abilities → capabilities → features → implementation → evidence**.
+The **Repository Scoping** provides a structured, inspectable orientation layer for code repositories by mapping them from **abilities → capabilities → features → implementation → evidence**.
 
 It enables developers, architects, and agents to:
 
@@ -487,7 +487,7 @@ Evidence:
 
 # 14. **Positioning**
 
-> The Repository Ability Registry is the missing orientation layer between raw code and practical reuse—making repositories understandable, comparable, and actionable.
+> The Repository Scoping is the missing orientation layer between raw code and practical reuse—making repositories understandable, comparable, and actionable.
 
 
 

wiki/RepositoryRegistry.md

@@ -1,3 +1,5 @@
+> Historical note: this page predates the rename to Repository Scoping. See `RepositoryScoping.md` for the current product identity and terminology.
+
 RepositoryRegistry
 
 *Exploring repositories by ability, capability and features*

wiki/RepositoryScoping.md

@@ -0,0 +1,44 @@
+# Repository Scoping
+
+Repository Scoping is the renamed and broadened product identity for the former
+Repository Ability Registry. It helps users register repositories, analyze them,
+curate repository characteristics, and publish a source-linked understanding of
+what each repository is for.
+
+## Core Workflow
+
+1. Register a Git URL or local checkout.
+2. Run analysis to collect deterministic observed facts.
+3. Review candidate scope graphs produced by deterministic heuristics and,
+   optionally, LLM assistance.
+4. Accept, edit, merge, reject, or relink candidates until the approved graph is
+   useful.
+5. Use the approved graph for UI orientation, search, comparison, exports, and
+   SCOPE.md generation.
+
+## Orientation Model
+
+The preferred model is:
+
+```text
+Scope -> Ability -> Capability -> Feature -> Evidence -> Observed fact
+```
+
+Scope is the single root. Abilities, capabilities, and features are repository
+characteristics at decreasing abstraction levels. Evidence explains why a
+characteristic is credible. Observed facts are deterministic scanner records,
+not human interpretation by themselves.
+
+## Rename Notes
+
+The user-facing name is Repository Scoping and the repo slug is `repo-scoping`.
+The Python package remains `repo_registry`, and local configuration still uses
+`REPO_REGISTRY_` for compatibility. Documentation should use Repository Scoping
+for product references unless it is intentionally discussing historical material.
+
+## Current Product Direction
+
+The UI should lead with scope, abilities, capabilities, and features, with facts
+available as drilldown evidence rather than as the primary orientation surface.
+Candidates and approved entries are most useful when shown together with filters
+for status, type, and search text so overlap and duplicates can be normalized.

wiki/UseCaseCatalog.md

@@ -4,11 +4,11 @@ UseCaseCatalog
 
 # Use Case Catalog
 
-## Repository Ability Registry
+## Repository Scoping
 
 ## 1. Scope
 
-The **Repository Ability Registry** allows users to register Git repositories, analyze their contents, extract or maintain structured descriptions of their **abilities, capabilities, features, evidence, and implementation locations**, and make this information searchable through efficient interfaces and a web UI.
+The **Repository Scoping** allows users to register Git repositories, analyze their contents, extract or maintain structured descriptions of their **abilities, capabilities, features, evidence, and implementation locations**, and make this information searchable through efficient interfaces and a web UI.
 
 Core promise:
 

workplans/RREG-WP-0007-final-rename-polish-and-knowledge-capture.md

@@ -0,0 +1,68 @@
+---
+id: RREG-WP-0007
+type: workplan
+title: "Final Rename Polish and Knowledge Capture"
+domain: capabilities
+repo: repo-scoping
+status: done
+owner: codex
+topic_slug: foerster-capabilities
+created: "2026-05-01"
+updated: "2026-05-01"
+state_hub_workstream_id: "aff1e797-db89-4ae5-b0c9-37035bf6bdd5"
+---
+
+# Final Rename Polish and Knowledge Capture
+
+This final cleanup workplan captures the small but important repo-scoping
+identity and knowledge-transfer tasks before the compatibility symlink for the
+old checkout name is removed.
+
+## Rename Visible Application Identity
+
+```task
+id: RREG-WP-0007-T01
+status: done
+priority: high
+state_hub_task_id: "7e73eb23-6253-4c0a-9a56-eb6da3b60992"
+```
+
+Rename user-facing application surfaces from "Repository Ability Registry" to
+"Repository Scoping" while keeping implementation compatibility names such as
+the `repo_registry` Python package and `REPO_REGISTRY_` environment prefix.
+
+## Clean SCOPE.md Stale Notes
+
+```task
+id: RREG-WP-0007-T02
+status: done
+priority: high
+state_hub_task_id: "2ce5efd9-5170-4a48-a165-3e52cb46cba5"
+```
+
+Review `SCOPE.md` and remove notes that describe temporary rename blockers or
+old checkout paths.
+
+## Present SCOPE.md In The UI
+
+```task
+id: RREG-WP-0007-T03
+status: done
+priority: medium
+state_hub_task_id: "ca31df4e-5608-46d7-95dd-5036a07d6c26"
+```
+
+Expose the repository `SCOPE.md` through the curator UI so the canonical scope
+summary is visible without leaving the application.
+
+## Capture Documentation And Terminology
+
+```task
+id: RREG-WP-0007-T04
+status: done
+priority: medium
+state_hub_task_id: "08619f91-db8e-471f-9616-8a468819b0f5"
+```
+
+Add durable docs/wiki pages that preserve the product terminology, rename
+context, and characteristic model knowledge for future sessions.