repo-scoping/README.md

# Repository Ability Registry

The Repository Ability Registry 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.

## Local Development

Create an environment and install dependencies:

```bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

Run the API:

```bash
uvicorn repo_registry.web_api.app:app --reload
```

The API creates a local SQLite database at `var/repo-registry.sqlite3` by default.

## First API Loop

```bash
curl -X POST http://127.0.0.1:8000/repos \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com/mail-router.git"}'
```

The registry imports name and description from `pyproject.toml`, `package.json`, or README where possible. Then add abilities, capabilities, features, and evidence under that repository and inspect:

```bash
curl http://127.0.0.1:8000/repos/1/ability-map
curl 'http://127.0.0.1:8000/search?q=classify'
```

## Deterministic Analysis

For local development, repository URLs may be local filesystem paths. Git URLs, including `file://` URLs, are cloned into `var/checkouts` before scanning. Trigger a deterministic scan:

```bash
curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs \
  -H 'content-type: application/json' \
  -d '{}'
```

Or override the scan source path explicitly:

```bash
curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs \
  -H 'content-type: application/json' \
  -d '{"source_path":"/path/to/repository"}'
```

Inspect recorded facts:

```bash
curl http://127.0.0.1:8000/repos/1/analysis-runs
curl http://127.0.0.1:8000/repos/1/observed-facts
```

The deterministic scanner records observed facts only: languages, documentation files, examples, tests, package manifests, configuration files, framework hints, and likely API/CLI interfaces.

Each completed analysis run also creates a conservative candidate graph for review:

```bash
curl http://127.0.0.1:8000/repos/1/analysis-runs/1/candidate-graph
```

Candidate entries are source-linked review seeds. They are not canonical registry truth until a review workflow approves them.

Approve a candidate graph into the canonical registry:

```bash
curl -X POST http://127.0.0.1:8000/repos/1/analysis-runs/1/candidate-graph/approve \
  -H 'content-type: application/json' \
  -d '{"notes":"Approved first review package"}'
```

Approval copies candidate abilities, capabilities, features, and evidence into the approved registry tables, marks candidates approved, and moves the repository status to `indexed`.