feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,110 @@
+# 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.