Merge pull request #31 from OpenScience-Collective/docs/osa-public-feeds

docs(osa): document public FAQ and citations feeds

Author: neuromechanist

docs/osa/api-reference.md

@@ -207,6 +207,126 @@ Ephemeral database mirror management. See [Database Mirrors](mirrors.md) for ful
 | `POST` | `/mirrors/{id}/sync` | Run sync pipeline |
 | `GET` | `/mirrors/{id}/download/{community}` | Download SQLite file |
 
+## Public Data Feeds
+
+Communities can expose two **read-only, unauthenticated** JSON feeds for building
+their own frontends (dashboards, widgets, citation badges). Both are **opt-in per
+community** via the `public_feeds` config block and return **404** when the feed is
+not enabled. Responses are cacheable (`Cache-Control: public, max-age=3600`).
+
+Currently enabled: **EEGLAB** (FAQ + citations) and **BIDS** (citations).
+
+### FAQ Feed
+
+Synthesized question/answer entries generated from a community's mailing-list and
+forum archives.
+
+```
+GET /{community}/faq
+```
+
+No authentication required. Returns **404** if `public_feeds.faq` is not enabled.
+
+Query parameters:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `q` | string | – | Full-text search phrase. Omit to browse all entries. |
+| `category` | string | – | Filter by category (`how-to`, `troubleshooting`, `reference`, `bug-report`, `feature-request`, `discussion`). |
+| `min_quality` | float | `0.0` | Minimum quality score (0.0–1.0). |
+| `limit` | int | `50` | Page size (1–200). |
+| `offset` | int | `0` | Pagination offset (ignored when `q` is set). |
+
+Response:
+
+```json
+{
+  "community_id": "eeglab",
+  "total": 1990,
+  "limit": 50,
+  "offset": 0,
+  "entries": [
+    {
+      "question": "How do I run ICA in EEGLAB?",
+      "answer": "Use runica from the Tools menu...",
+      "tags": ["ica", "preprocessing"],
+      "category": "how-to",
+      "quality_score": 0.95,
+      "message_count": 4,
+      "first_message_date": "2020-03-11",
+      "thread_url": "https://sccn.ucsd.edu/pipermail/eeglablist/..."
+    }
+  ]
+}
+```
+
+`total` is the count of entries matching the filters (before pagination). Email
+addresses are redacted from `question`, `answer`, and `tags`.
+
+```bash
+# Browse the highest-quality how-to entries
+curl "https://api.osc.earth/osa/eeglab/faq?category=how-to&min_quality=0.8&limit=10"
+
+# Search
+curl "https://api.osc.earth/osa/eeglab/faq?q=ICA%20components"
+```
+
+### Citations Feed
+
+Per-year citation counts for a community's canonical papers, suitable for a stacked
+"citations per year" chart. Counts come from OpenAlex (complete and uncapped); a
+paper's preprint and published versions are merged and deduplicated, and counts are
+floored at the paper's earliest publication year.
+
+```
+GET /{community}/citations
+```
+
+No authentication required. Returns **404** if `public_feeds.citations` is not
+enabled. Takes no query parameters.
+
+Response:
+
+```json
+{
+  "community_id": "bids",
+  "total": 3098,
+  "per_year": { "2016": 22, "2017": 48, "...": 0, "2025": 502 },
+  "by_paper": {
+    "10.1038/sdata.2016.44": { "2016": 22, "2017": 48, "...": 0 },
+    "10.1038/s41597-019-0104-8": { "2019": 12, "...": 0 }
+  },
+  "canonical_dois": ["10.1038/sdata.2016.44", "10.1038/s41597-019-0104-8"],
+  "labels": {
+    "10.1038/sdata.2016.44": "BIDS (Gorgolewski 2016)",
+    "10.1038/s41597-019-0104-8": "EEG-BIDS (Pernet 2019)"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `total` | Total citing works across all canonical papers. |
+| `per_year` | Citing-work count per publication year, summed across papers. |
+| `by_paper` | Stacked breakdown: canonical DOI → year → count. |
+| `canonical_dois` | The DOIs tracked for this community (config order). |
+| `labels` | Human-readable label per DOI for chart legends (when configured). |
+
+```bash
+curl "https://api.osc.earth/osa/bids/citations"
+```
+
+```python
+import httpx
+
+data = httpx.get("https://api.osc.earth/osa/bids/citations").json()
+years = sorted(data["per_year"])
+for doi, by_year in data["by_paper"].items():
+    label = data["labels"].get(doi, doi)
+    series = [by_year.get(y, 0) for y in years]
+    print(label, series)
+```
+
 ## Request Parameters
 
 ### Ask Request

docs/osa/registry/schema-reference.md

@@ -20,6 +20,7 @@ Complete reference for the community `config.yaml` file format.
 | `documentation` | list | No | `[]` | Documentation sources |
 | `github` | object | No | `null` | GitHub sync configuration |
 | `citations` | object | No | `null` | Paper/citation search config |
+| `public_feeds` | object | No | `null` | Opt-in public read-only JSON feeds (FAQ, citations) |
 | `docstrings` | object | No | `null` | Code docstring extraction config |
 | `mailman` | list | No | `[]` | Mailing list archive configs |
 | `faq_generation` | object | No | `null` | LLM-based FAQ generation config |
@@ -222,6 +223,9 @@ Paper search and citation tracking configuration for the knowledge database.
 |-------|------|----------|---------|-------------|
 | `queries` | list[string] | No | `[]` | Search queries for OpenALEX |
 | `dois` | list[string] | No | `[]` | Core paper DOIs to track (format: `10.xxxx/yyyy`) |
+| `live_search` | bool | No | `false` | Expose an on-demand live paper-search tool |
+| `paper_labels` | map[string, string] | No | `{}` | Human-readable label per DOI for the citations dashboard legend |
+| `aliases` | map[string, list[string]] | No | `{}` | Version DOIs (preprint, etc.) to merge into a primary DOI's citation count |
 
 ```yaml
 citations:
@@ -231,9 +235,44 @@ citations:
   dois:
     - "10.1016/j.neuroimage.2021.118766"
     - "10.1007/s12021-023-09628-4"
+  # Labels shown in the public citations chart legend
+  paper_labels:
+    "10.1016/j.neuroimage.2021.118766": "HED-NeuroImage (2021)"
+  # Merge a preprint into the published paper's citation count (deduplicated)
+  aliases:
+    "10.1016/j.neuroimage.2021.118766":
+      - "10.1101/2021.01.01.000000"
 ```
 
-DOIs are validated against the `10.xxxx/yyyy` pattern. Common URL prefixes (`https://doi.org/`, `https://dx.doi.org/`) are automatically stripped.
+DOIs are validated against the `10.xxxx/yyyy` pattern. Common URL prefixes (`https://doi.org/`, `https://dx.doi.org/`) are automatically stripped. The same normalization and validation apply to `paper_labels` keys and `aliases` keys/values; every `aliases` primary key must also appear in `dois`.
+
+**`aliases` — why:** OpenAlex keeps separate records for a paper's preprint and published versions and splits citations across them. Listing the version DOIs under `aliases` makes the citation sync query them together (OR-joined, deduplicated) and attribute the merged per-year counts to the primary DOI. Counts are floored at the earliest version's publication year, so no paper reports citations before it existed.
+
+`paper_labels` and `aliases` feed the public [citations dashboard](#public_feeds) and the `GET /{community}/citations` endpoint.
+
+## `public_feeds`
+
+Opt-in flags that expose community data as **public, read-only JSON feeds** so
+communities can build their own frontends. Both are **off by default**.
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `faq` | bool | No | `false` | Expose generated FAQ entries at `GET /{community}/faq` |
+| `citations` | bool | No | `false` | Expose citation counts at `GET /{community}/citations` |
+
+```yaml
+public_feeds:
+  faq: true
+  citations: true
+```
+
+- `faq: true` requires a configured FAQ pipeline (`mailman` + `faq_generation`) with
+  synced entries; otherwise the feed is empty.
+- `citations: true` requires `citations.dois`; counts populate on the next citation
+  sync.
+
+See the [API Reference](../api-reference.md#public-data-feeds) for the endpoint
+shapes, query parameters, and examples.
 
 ## `maintainers`
 

docs/osa/status.md

@@ -10,6 +10,7 @@ The new dashboard includes:
 
 - **Aggregate overview** with total requests, error rates, and community breakdown
 - **Per-community views** with usage charts and tool statistics
+- **Publication citations** chart (stacked by canonical paper, per year) for communities that expose the [citations feed](api-reference.md#citations-feed)
 - **Sync health status** for GitHub and papers knowledge sources
 - **Admin section** for token usage and cost metrics (requires API key)