# Research Address-Book Repositories

Use this pattern when a Gitea repository is intended to map a broad ecosystem, organization network, infrastructure landscape, or other changing domain.

## Design principle

Start with an **address book of authoritative directories and coordinating bodies**, not an attempted exhaustive list of every participant. Large ecosystems change too quickly for a hand-maintained flat inventory. Anchor later ingestion to official registries, public directories, and primary sources.

Separate four concerns:

1. Human navigation and concise summaries.
2. Canonical machine-readable records.
3. Method, taxonomy, and analytical findings.
4. Unverified leads and future research.

## Recommended structure

```text
.
├── README.md
├── address-book/
│   ├── README.md
│   └── <category>.md
├── data/
│   ├── README.md
│   └── entities.csv
├── docs/
│   ├── 01-scope-and-method.md
│   ├── 02-first-round-investigation.md
│   └── 03-taxonomy.md
├── research/
│   └── next-round.md
├── scripts/
│   └── validate.py
├── sources/
│   └── README.md
├── CONTRIBUTING.md
└── Makefile
```

Keep the top level small and obvious. Number only documents that have a reading sequence. Prefer category pages over one giant address-book document.

## Round-1 data model

CSV is a strong first format because it is Git-readable, spreadsheet-compatible, and dependency-free. Useful columns:

```text
id,name,category,scope,region,homepage,directory_url,role,source_url,status,verified_at,notes
```

Conventions:

- `id`: stable lowercase kebab-case; never recycle IDs.
- `category`: controlled taxonomy, based on function rather than assumed hierarchy.
- `scope`: distinguish global, regional, and regional-community scope.
- `region`: service or community coverage, not merely headquarters.
- `directory_url`: best public discovery, contact, membership, registry, or data entry point.
- `source_url`: primary evidence for the role claim.
- `status`: `verified`, `partial`, `lead`, or `stale`.
- `verified_at`: UTC date in `YYYY-MM-DD`.
- `notes`: caveats about automated access, completeness, ownership, or interpretation.

Move to versioned JSON/YAML records only when nested relationships, source merges, or repeated attributes make CSV inadequate. Do not add a database just for presentation.

## Research method

1. State the research question and explicit boundary.
2. Build a functional taxonomy; do not force decentralized ecosystems into a false parent/child hierarchy.
3. Identify globally or regionally authoritative directories and coordinating bodies.
4. Prefer official registries, APIs, standards bodies, and operator-maintained sources.
5. Verify URL reachability, but distinguish transport success from factual proof.
6. Put canonical entries in structured data; keep hypotheses in `research/`.
7. Write a first-round synthesis explaining findings, evidence limits, and missing coverage.
8. Define the next research rounds before adding automation.

## Provenance and contact safety

- Prefer public institutional and role-based contact points.
- Do not publish private personal data, credentials, or member-only incident contacts.
- A registry record does not necessarily establish current operator, owner, or beneficial controller.
- Community-maintained databases and measurement collectors expose partial viewpoints; document coverage caveats.
- A `403` from an automated client may be an access-policy caveat, not evidence that the official URL or entity is invalid. Record the caveat and use browser/manual verification when appropriate.

## Validation

Provide a standard-library-only validator where practical. Check:

- exact required columns;
- non-empty required fields;
- unique and well-formed IDs;
- controlled taxonomy/status values;
- HTTPS URLs;
- parseable, non-future verification dates;
- presence of required orientation documents.

Expose predictable commands:

```bash
make validate
make summary
```

Before push:

```bash
git diff --cached --check
make validate
```

After push, verify both the Git ref and at least one distinctive remote artifact using the authenticated Gitea API. A successful push message is useful evidence, but authenticated readback confirms the requested content rather than only the ref update.